"Documentation by paper"

[Joe Buck]

On Wed, Feb 04, 2004 at 09:11:29AM -0500, Richard Kenner wrote:
> How could I possibly write documentation on code that I need documentation
> to understand?  Any documentation I could write would be totally useless!

In my experience, the best documention is written by someone with good
technical writing skill as well as some programming knowledge who
initially doesn't understand the code, but who learns what he or she needs
to know by a dialog with the author.  The process of generating the
documentation this way often uncovers bugs, which fall out when the coder
can't explain something, or can't answer a question about a boundary case.