"Documentation by paper"

[Joe Buck]

On Wed, Feb 04, 2004 at 01:07:40PM -0500, Richard Kenner wrote:
>     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.  
> 
> I agree you can develope *adequate* documentation that way, but strongly
> disagree that it's the *best*.

OK, the *best* would be written by that almost non-existent programmer who
combines a love of writing clear English prose with the extraordinary
discipline required to do it first and keep it current.  But since this
species is almost non-existent, you need to read my phrase "best
documentation" for "best documentation achievable in practice".

In any case, we have to go from what we have: right now we have code that
is not adequately documented.  Time travel is not an option.