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: matz at suse dot de, gcc at gcc dot gnu dot org
- Date: Wed, 4 Feb 2004 09:50:12 -0800
- Subject: Re: "Documentation by paper"
- References: <10402041411.AA29202@vlsi1.ultra.nyu.edu>
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.