RE: Documentation... Program Comments...

["Jewel, Jerry" <jerry.jewel@xxxxxxxxxxxxxx>]

> Joe Giusto wrote:
> 
> > We (MIS Dept) have been asked to develop a plan to have our entire
> > system documented by year end (by september if possible).  Just in
> case
> > our entire MIS staff would be hit by a truck at the same time.  the
> > ultimate goal would be for a temp staff to be able to come in and
> > continue operations/programming activities if something were to
> happen
> > to one or all of us.
> 
Well commented code is vital, but only the beginning of good
documentation.

Before you, or someone you hire (IM NOT SUGGESTING ME BY THE WAY) start,
it is important to have a clear idea of exactly what deliverable you
need for a "documented system".  If you don't already have a realistic
sample, create one on a very small piece of your system.  Focus on the
audience for the documentation.

I suggest a multi-pronged attack utilizing a combination of
tools/people:

o   Create good program generated map of your system via Hawkeye,
Probe/Abstract, or other such tool.  This will give you a head start.

o  Using a tape recorder, have a programmer (hopefully someone familiar
with the program) dictate a brief description of each program.  Use a
bullet point list of items that should be covered.

o  Using a tape recorder, have a systems person (hopefully someone
familiar with the system) dictate a brief description of each
system/subsystem.  Use a bullet point list of items that should be
covered.

o  Have the tapes transcribed by a service.  (Not your technical
people.)  

o  Have a technical writer edit/update the program and system
descriptions.

This should give you a leg up on the documentation monolith.  HTH.

Regards,
Jerry Jewel       

jerry.jewel@nissan-usa.com
Better living through fine code and hot coffee!



+---
| This is the Midrange System Mailing List!
| To submit a new message, send your mail to MIDRANGE-L@midrange.com.
| To unsubscribe from this list send email to MIDRANGE-L-UNSUB@midrange.com.
| Questions should be directed to the list owner/operator: david@midrange.com
+---