2 ms·
I am becoming fascinated by finding better ways to document and communicate about code - not just writing good docs as part of checkin but, well lets say we tak
by lifeisstillgood 14y ago
I am becoming fascinated by finding better ways to document and communicate about code - not just writing good docs as part of checkin but, well lets say we take on a feature.
We should propose how to implement that feature, (spec) get some feedback, go do it, review the implementation against the spec and even then I would want to have a sort of stack overflow Q&A site so people can ask why did you do that ?
Anyone else feel we are missing a whole boatload of tricks?
- Hoff 14y agoWhen working on or editing documentation or the comments, I start with the "two-year-old kid" review. I ask myself "why" and "what", and often repeatedly, until I get to a concise answer. What's this? Why is this here? Why do I want it? Why is this good? Why do I care? Why? What's that mean? What's this knob do? What's that code do? Why is this code here? Why? Flabby documentation, user documentation written in programmer jargon and scatter-shot code comments are all comparatively easy to write. When somebody bothers to write that. Writing for the end-user (whoever that might be) is tougher, and I find require iterating on the content of the documentation, UI, release notes, comments, or whatever. Writing less documentation or fewer comments — while conveying the necessary details — is hard work.