Re: "Documentation by paper"

[Robert Dewar <dewar at gnat dot com>]

Michael Matz wrote:

> You are global write, you can surely apply your documentation patches on 
> your own.  Oh wait ...

There's something very wrong here. It is essential that documentation
be written as the code is produced, or where feasible *before* the
code is produced. Adding documentation after the fact is almost
never satisfactory for several reasons.

1. The style of adding documentation after the fact tends to go along
with a viewpoint of documentation as some kind of annoying extra
junk work, which is not conducive to getting good documentation.

2. It encourages a style of "I will write the code, but someone
else can document it if they really need documentation". This is
a variation of "real programmers don't need no !@# documentation"
and again is not conducive to getting good documentation.

3. By the time the program is all working, you may well have forgotten
details that in fact are quite critical for understanding things.
Better to write the documentation at the point where you are working
to understand things, and they are fresh in your mind.

4. In the case where someone else is expected to provide this
documentation (apparently what Michael has in mind here), the
process of groveling through code to reconstruct the documentation
can never succeed for two fundamental reasons:

   4a. You end up documenting what the code does, instead of what
       it is supposed to do.

   4b. You can document what the code does, but not why particular
       choices of implementation were made.

   4c. An important part of documentation is what you did NOT do
       and why you did NOT do it. That can never be deduced from
       the code

Note that paragraph 4 here also shows why "code groveling" itself
can never substitute for good documentation.