Writing Documentation (was: Re: Shouldn't the fact that beagle doesn't work with both firefox and thunderbird be a release blocker?)

[Patrick O'Callaghan]

On Fri, 2009-05-22 at 11:10 -0700, stan wrote:
> Speaking as an (ex?) programmer, writing the code is fun, writing the
> documentation is pure drudgery.  And really, the 
> only person who can realistically write documentation is the
> programmer.  They know all the ins and outs of the code, 
> and the functionality they programmed in.  It can be done through an
> intermediary, someone who questions the programmers 
> and finds out the functionality and then writes it in comprehensible
> language, but the chance that someone unfamiliar 
> with the code is going to write decent documentation is pretty slim.
> 
> Of course, in the days when code was written to specs, the specs were
> the kernel of the documentation and only needed to 
> be modified with changes.  I don't think there are such things as
> specs in the open source world, just some general 
> vision statement of what the software should accomplish, usually about
> as detailed as the description from the RPM. :-)

My view is that if the programmer can't write a lucid description of
what his stuff does, it means he doesn't really understand it himself.
This doesn't mean writing a three-line comment for every internal
function, it means having a coherent conception of what your program is
for and how it works, and being able to explain at least the former at a
level appropriate to the target user.

There's a strong correlation between good code and good docs. The idea
that writing the docs is drudge-work best left to an intern does profund
damage to the image of programming as a serious activity.

poc