Re: Documenting Code

["MacDonald, Stephen" <Stephen -dot- MacDonald -at- Aspect -dot- com>]

> I'm 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.

It's not a whole lot different from writing a manual for users:

o Identify the audience and what information they need (usually the
engineers doing maintenance on the code)
o Identify any coding standards regarding documentation.
o Identify who wrote what code so you'll know who the SMEs are.

The comments in each piece of code should do essentially the following:

o Present an overview of what the code is for (what job does it do in the
application?)
o Define what information, if any, is passed to the code to be processed
o Explain how it processes the information (description of the algorithm,
etc.)
o Define what result (data, changed state, etc.) comes from the code
o Any historical change or identifying information the organization
requires, that is, what application's) is it used in, what versions, etc.

If there isn't one already, develop a simple, consistent format for
presenting this information so that a person who knows the format can
quickly find comments and pick out of it the part they are interested in. 

This is a good thing your organization is doing.  You get to work closely
with the  engineers to produce something that matters to them directly.
It's a great opportunity to establish rapport useful to you later.

Steve MacDonald
Aspect Communications, Inc.