Re: Code Documentation

[Bruce Boyer <bboyer -at- OBJECTSHARE -dot- COM>]

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
************
Bruce Boyer, Ph.D.
Lead Technical Writer
ObjectShare
email: bboyer -at- objectshare -dot- com
************


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