Re: Documenting Code

Subject: Re: Documenting Code
From: "MacDonald, Stephen" <Stephen -dot- MacDonald -at- Aspect -dot- com>
To: "'TECHWR-L -at- LISTS -dot- RAYCOMM -dot- COM'" <TECHWR-L -at- LISTS -dot- RAYCOMM -dot- COM>
Date: Fri, 21 Jul 2000 08:42:03 -0400


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






Previous by Author: Thanks and Apologies
Next by Author: RE: Outrageous: Was Pray for me
Previous by Thread: Re: Documenting code
Next by Thread: Re: Humor: from a *real* job posting!


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


Sponsored Ads