Re. Documenting code?

[Geoff hart <ghart -at- attcanada -dot- ca>]

Ken Wasden is <<...new 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 
means.'>>

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 
programming.

--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