[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: Building prog first

From: Steffen Dettmer
Subject: Re: Building prog first
Date: Tue, 23 Mar 2010 11:41:07 +0100


On Mon, Mar 22, 2010 at 11:50 PM, John Calcote <address@hidden> wrote:
> Reuben, you've just hit upon one of the two most significant
> problems with Javadoc and the like (including doxygen, man
> pages, and info pages):

sorry, I cannot leave this, because this would be an excuse for
people `but we have to use Javadoc, so we cannot document well',
which is not true (you said this in your point 2, but I have to
stress it :-)).

It is not a problem of the tools, but of the documentation.
When the main pages in Javadoc and Doxygen documentation are well
written, introduce well, include examples and reference important
functions, who in turn include example code (often telling more
than 1000 words :-)) and again reference functions often needed
in this context, this can help really a lot.

I think:

1) Someone has to know (learn) the API before starting to use it.
   (read documentation, make examples) If there is no good
   documentation and/or no good examples, it would be great to
   write and contribute :-)

2) Documentation should be written aimed at the target audience.
   As other software, it must be structured well, easy to read,
   understand and maintain. Usually it must evolve, first time is
   always bloody.
   Also, it should be tested (e.g. reviewed).

I think often the problem leading to just have documentation like

 * Uses the passed wizard, which must be a Mage, to do the magic.
doMagic(Mage wizard);

is that people agree that documentation is important but didn't
considered well how to do it best. I'm afraid often documentation
is considered something `that has to be done also', quickly by
the side, instead of considering it as one of the most important
parts of the software (it's easy to fix a bug when the
documentation clears how it should be, but it's hard to fix
documentation when the code behaves oddly).

Well, you all know this but I could not resists to write it anyway :)



reply via email to

[Prev in Thread] Current Thread [Next in Thread]