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