TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
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.
Bruce Boyer, Ph.D.
Lead Technical Writer
email: bboyer -at- objectshare -dot- com