This is the mail archive of the
gcc@gcc.gnu.org
mailing list for the GCC project.
Re: "Documentation by paper"
- From: Joe Buck <Joe dot Buck at synopsys dot COM>
- To: Richard Kenner <kenner at vlsi1 dot ultra dot nyu dot edu>
- Cc: gcc at gcc dot gnu dot org
- Date: Wed, 4 Feb 2004 10:57:51 -0800
- Subject: Re: "Documentation by paper"
- References: <10402041807.AA02460@vlsi1.ultra.nyu.edu>
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.