Re: Code Documentation

Subject: Re: Code Documentation
From: Linda Sherman <linsherm -at- GTE -dot- NET>
Date: Tue, 10 Nov 1998 20:59:29 -0500

Jim Aikens wrote:
> Tracey Moore wrote:
> >we now need to document the code.
> >
> >How do you document?
> But who are you documenting it for? If it is for programmers, then I can
> only urge that you forget about creating a document. It is wasteful and
> dangerous to document program code externally.

Speaking as a veteran programmer, I partly agree with this. The
low-level details should most definitely be documented in the code. But
some things are better explained externally (not necessarily in hard
copy, though).

An example would be a large class library or application framework.
Without some sort of coherent and well-organized online reference,
determining the class hierarchies, inheritances, and overrides by simply
rummaging through header files would be a migraine and a half.

Another case where I think external documentation is very useful is an
API. I'd really rather see a well-written textual description of each
interface function organized alphabetically in a hardcopy manual or
online refernece than have to hunt through header files to find out what
the API is capable of and how to get it to do it.

I can't answer Tracey's question, though, without knowing whom the
documentation is for and what it proposes to accomplish.

Linda K. Sherman <linsherm -at- gte -dot- net>
Freelance Writer: Technical - Business - Government

From ??? -at- ??? Sun Jan 00 00:00:00 0000=

Previous by Author: [Fwd: graphics package]
Next by Author: Re: Citing HTML tags in docs?
Previous by Thread: Re: Code Documentation
Next by Thread: Font Choices

What this post helpful? Share it with friends and colleagues:

Sponsored Ads