TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
In a message dated 4/14/98 10:31:58 AM EST, Debbie_Stewart -at- SIECOR -dot- COM writes:
<< We have hundreds of COBOL programs here and I am being assigned the task
to
inventory and document them. Fun, huh? Because of Y2K and turnover,
we have a need to get some control on the business critical programs.
Does anyone out there have a list, template, or process they use to
document existing code? >>
New or existing, I've always tried to get a few basics in:
- The name of the program/routine (COBOL enforces this and some of the other
pieces automatically, unlike lots of other languages)
- Who wrote it and when
- Who modified it and when (hard to recover after, though)
- What it does
- What program or JCL calls it
- What programs it calls
Data elements should be (briefly) defined in terms of their real-world
meaning.
Every main and calling routine should have an explanation of its purpose at
the start. If a routine is longer than a page (or a screen or two),
explanations should appear for each major function within it. (I've been known
to go to almost pseudo-code level here, but in fact that can get cluttered if
you're not careful.)
I can't imagine a 'template' per se for all this, since the overall form of
the program is pretty much established before you document it.
Jim Chevallier
Los Angeles
==Visit Chez Jim: Jim Chevallier's home page - htpp://www.gis.net/~jimcheval
====
