(OT) On Mon, Mar 22, 2010 at 11:50 PM, John Calcote <[email protected]> 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 :) oki, Steffen
