Re: Management of products and projects

[Karen Coyle <karen.coyle@ucop.edu>]

At 07:23 AM 8/20/00 -0400, Eric Lease Morgan wrote:
>
>Fourth, document your work. There are two types of documentation.

This is a key point, and one where most of us fall short of the mark. And
I'd actually like to add a third kind of documentation, at least for
programs that are longer than a module or two: documentation of the
program's structure, inputs and outputs, and error codes and conditions. 

Here's how I look at the kinds of documentation:

1) Documentation within code: This is for the programmer who comes along
after you to make changes or add new features. In this situation the
programmer is already in the code trying to figure out exactly what it does.

2) Overall program documentation: This is for the programmer or analyst who
is trying to figure out what the program does and does not do and whether
it can be updated or modified for the new requirements. Reading the code to
determine this, especially for large programs, is highly inefficient. It
also helps other programmers locate the proper place within a large program
to begin working. 

3) User documentation: How to run the program. Quirks of what it does and
does not accept as input. Full list of parms and their formats. Full list
of error codes and what to do when they happen. 



----------------------------------------------
Karen Coyle                    karen.coyle@ucop.edu
  University of California Digital Library
  http://www.kcoyle.net        510/987-0567
----------------------------------------------