Documentation Standards › Considerations

Considerations

• Prescriptive and Descriptive Documentation—It is useful to distinguish between prescriptive and descriptive documentation.

Prescriptive documentation is needed before a system exists, in order to specify what it will be like. It may include computer-based definitions such as prototypes or data models. Prescriptive documentation includes high-level system definition documentation, such as a requirements specification or a component architecture overview.

Descriptive documentation is needed after a system exists to record what it does. There is considerable scope for producing most descriptive documentation automatically from the objects and source that comprise an application. The CA 2E Toolkit application documentation utilities mostly produce descriptive documentation, which is detailed here.

• Documentation Principles—The following principles should be followed in preparing documentation:
  • Use design and implementation tools that provide integrated documentation facilities.
  • Use computer-based word processing and/or DTP facilities to prepare additional text documentation.
  • As far as possible, make use of the computer in collating and ordering documentation.
  • Ensure all objects and documentation have descriptive titles so as to facilitate the automatic preparation of indices and cross-references.
  • Use standards to reduce the amount of documentation. Too much documentation can be as bad as too little documentation.
  • Use computer-based tools that can create documentation from existing systems.
  • Each program should have a functional synopsis that can be extracted to provide a summary of its function. "Meaning" will still have to be provided by human intervention.
  • Provide diagrams wherever possible.

Once a system is implemented, the majority of documentation will probably only be required to cope with change, either to the system or of personnel. Take a facultative approach to the actual production of your documentation\-\-— that is to say it should only actually be created when required, but the capability to produce it on demand should be built into the system. Software tools to produce facultative documentation should include scanning, cross-referencing, and list handling facilities. Ideally, it should be possible to produce different views of the documentation to meet different types of users’ needs, for instance, analyst, tester, and programmer. The computer should regenerate all but the highest level of documentation automatically. This means that it will automatically stay up-to-date if changes are made.

The following diagram shows the organization of system documentation as a pyramid of levels: the commands used to print the documentation at each level are shown in bold type in brackets. It should be possible to produce all of the documentation up to the dotted line automatically.

• Computer-Generated Documentation—The following documentation can be generated for all application systems, using the CA 2E Toolkit documentation utilities:
  • File layouts: The CA 2E Toolkit Document File (YDOCF) command will generate file documentation from compiled files, and will include information about fields, access paths, and dependent files.
  • Menus: The CA 2E Toolkit Document Menu (YDOCMNU) command will generate documentation for CA 2E Toolkit menus.
  • Program summaries: The CA 2E Toolkit Document Program (YDOCPGM) utility will generate program documentation, including information about parameters, required objects, and subprograms called. In order for the utility to generate full documentation, ‘H*’ source directive lines must be used in the source as comments.
  • Source listings: The CA 2E Toolkit Document Source (YDOCSRC) utility will provide compact source listings.
  • Search listings: The CA 2E Toolkit Scan Source (YSCNSRC) utility will provide listings of occurrences of given search strings in source.
  • Cross-references: A variety of cross-references can be created using CA 2E Toolkit commands; for example, program/file, menu/program.
• Manually Generated Documentation—The following documentation should be prepared for all application systems:
  • Program Synopses: The comment section at the beginning of the source of every program should contain a statement of the purpose of the program and a summary of the functions carried out by the program.
  • Command diagrams: A standard command diagram should be provided for each command. Use a word processor to enter and to print command diagrams.
  • Message text: Message text, including second level text, should be prepared using the OS/400 Add Message Description (ADDMSGD) and Change Message Description (CHGMSGD) commands.
  • Help text: Operator instructions should be prepared for each interactive program. Use UIM help to provide help text. CA 2E will generate Help text automatically.
  • Summary flowcharts: Flowcharts and other diagram types indicating the main flow of information through the system should be prepared. The CA 2E Toolkit Work with Report (YWRKRPT) can be used to create simple diagrams up to 198 characters wide.
  • Technical overviews: Overviews should be written to describe the techniques used in the system, and to explain any special subjects; for example, backup, recovery, and end-of-period procedures.
• Command Based Documentation—A number of reasons were given earlier in this manual for arranging system design around user-defined CL commands, each command being the entry point to an application function. Not least among the reasons given was that CL commands provide a natural framework for arranging the operational documentation for the application, as well as a notation for doing so. The framework has a flat structure that enables the user to look up the operational details for invoking any task directly without having to locate it through a menu hierarchy.