Enterprise Applications
Development Guidelines and Procedures
Program Documentation
Purpose: To identify and standardize components required for effective documentation of programs. The following documentation components are required for each program developed with the intent that it is to be used multiple times. These apply whether the program is written in COBOL, Powerhouse, or other language. As an exception, QUIZ programs, which are quick and easy to produce, may have a listing maintained in the department's group under their control. This will be in lieu of the usual documentation. The intent is to reduce unnecessary documentation.
Components:
- Structure Chart
A structure chart, when created, should be contained in the System Manual. It provides a picture of the code as it appears in the program listing. The chart should be general in nature showing the logical design of the program and should not show each instruction.
- Program Specifications
A copy of the program specification as given to the programmer should be saved in the systems SYSDOC directory.
- Program Source Listing
Source listings should be maintained on-line in the DESIGN Account in the system's SOURCExy group for the system dictionary, QUICK screens, and COBOL programs. QUIZ and QTP programs are kept on HP1 in either the PRODQ or JOBS groups of the appropriate production account. Programs may also be kept in user groups on few occasions. The source includes author's name, date written, description, modification history, etc.. For documentation templates see Appendix E or F. Also, template files are provided on-line with a system code of xy. SCOMPARE listings prepared from the CHECKIN procedure on HP2 should be maintained in the system filing cabinet. Procedures should be developed to maintain SCOMPARE listings in our COLD product.
- Batch Jobs
Listings should be maintained in the JOBS group for batch jobs. These are jobs run by the customer. Each batch job prepared by Computer Center personnel should include internal documentation for identification and providing setup, run, and output disposition. Some batch jobs will contain information which should be passed on to Computer Operations. To facilitate this, STREAMX ECHO commands should be placed in the job stream which will remind the customer, upon streaming the job, that a computer operations work request is required for the job along with detail to be included in the work request.
- Sample Report
A short copy (first few pages) of a report may optionally be kept in the system filing cabinet and/or System Manual. Each report should have the name of the generating program included as part of the report heading.
- FORMSPEC Listing
A hardcopy FORMSPEC listing may optionally be maintained in the system filing cabinet.
- Sample Screen
A sample screen listing may optionally be maintained in system filing cabinet.
- Customer Documentation
As customers are instructed on the use of a new program they should be instructed on how to access customer documentation in QUICK screens.