Re: Code Documentation

Subject: Re: Code Documentation
From: Bruce Boyer <bboyer -at- OBJECTSHARE -dot- COM>
Date: Tue, 3 Nov 1998 12:47:57 -0800

At 02:45 PM 11/3/98 -0500, Tracey Moore wrote:
>My company has recently completed a visual basic/java application and we =
>now need to document the code. (All we've done so far is print out the =
>code itself.) Does anyone out there have experience with this?

Why are you documenting the code for an application? Assuming that's
really what you want to do...

>How do you document? What should the document look like? Any suggestions =
>on resources for sample documents?

Differentiate code samples from standard text, but don't over do it.
For instance, if normal text is serif, make code sans serif. Don't
pile up formats (e.g., don't add bold to the face change). There's
no need anymore to use monospace fonts; most editors aren't.

>As you can see, we're babies (uh, make that embryos) at doing this. =
>Thanks in advance for your help.

If you're documenting code, be very aware that your audience is probably
very different from what you're used to. They're still users, typically,
and so interested in what they need to know to use this thing, but it's
a very different kind of use. I'd guess you're documenting an API. It's
not necessary to document all the design decisions or to illustrate all
the implementation code, but clear examples of how to achieve a desired
end using the API is essential. Again, examples are essential.

Good luck

Bruce Boyer, Ph.D.
Lead Technical Writer
email: bboyer -at- objectshare -dot- com

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

Previous by Author: Re: Help! Font trouble ...
Next by Author: Re: User interface elements as a section itself in manuals
Previous by Thread: Code Documentation
Next by Thread: Re: Code Documentation

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

Sponsored Ads