Re. Documenting code?

Subject: Re. Documenting code?
From: Geoff hart <ghart -at- attcanada -dot- ca>
To: "Techwr-L (E-mail)" <techwr-l -at- lists -dot- raycomm -dot- com>, "'WebFamilies'" <kwasden -at- webfamilies -dot- com>
Date: Fri, 21 Jul 2000 08:24:56 -0400

Ken Wasden is << to the tech writing world, and have just been assigned
the task of documenting the code/comments of our latest software version.
Trouble is, I've never documented developers' code... I'm told the

documentation doesn't have to be perfected, exacting every detail of the code,
but rather touching the surface - 'The code says this, and this is what it

Understanding the goal of the documentation and the audience is always the most
important step in beginning any documentation project. Find out who you're
documenting it for, and find out precisely what _they_ need. One typical case
might be software that is now finished, and that nobody will look at again for
a year until they begin work on the next revision (e.g., the stuff I'm just
finishing the user docs for). They'll be busy with other projects, and when
they come back to the current one, they'll have forgotten much of the details
and need to quickly come up to speed so they can get back to work on version
3.X; similarly, they may have to drop what they're doing in 6 months and come
back to the current project to debug a faulty module.

At a basic level, all you may need to do is find each component of the code
(whether a module or subroutine or function) and provide the following
information: what the inputs are, what the outputs are, what the goal of the
module is, and what rules or cautions apply to the module. Here's an example
from the current software I'm finishing off: "The site definition module has no
inputs, and produces outputs that are used as inputs for all subsequent phases
of the harvesting operation. It produces the following outputs: volume per ha,
total areas, species, products, and... Cautions: None. Rules: Each harvest
block should be modeled as a separate site; the next phase following this
module must be a felling phase; areas and volumes must both be greater than
zero, ..."

More details may be necessary, up to an including the names and identities
(what they do) of each variable, but it doesn't sound like that's what they're
asking you. Ideally, this sort of thing should be done before programming
begins (as part of the design document) rather than after the fact, so you
probably have some kind of functional specification you can work from. Do a
good job of extracting that information and putting it to work in building the
actual code documentation and you may be invited back at the beginning of the
next project to help build the specifications. If you can get involved at that
stage, subsequent documentation will be much easier because (a) you'll
understand how the product works and (b) you'll be part of the team, and thus,
they won't spring any surprises on you when it comes time to actually start

--Geoff Hart ghart -at- netcom -dot- ca
"Most business books are written by consultants and professors who haven't
spent much time in a cubicle. That's like writing a firsthand account of the
Donner party based on the fact that you've eaten beef jerky."--Scott Adams, The
Dilbert Principle

Previous by Author: RoboHelp printed doc
Next by Author: RE: Writing first user manual. Advice?
Previous by Thread: Almost art, thanks
Next by Thread: Converting Frame to PDF

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

Sponsored Ads

Sponsored Ads