News for hackers. Stuff that matters.
Re:Documentation is King by lifeisstillgood on Sunday December 02, 2012 @07:02AM (#4860953)
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?

Re:Documentation is King by Hoff on Sunday December 02, 2012 @08:32AM (#4861121)
When 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.