THE PROGRAMMER'S DOCUMENTATION RESPONSIBILITIES

Proper program documentation is extremely important to the success of a data processing installation. It is essential to the effective operation of all affected departments, that complete and accurate documentation be available for reference during resolution of oper-ational problems.

There are two distinct classes of documentation in a programming assignment. One, classi-fied as technical documentation, provides exact information about the design and content of the program. The other classification comprises the operator instructions. Both classes should be collected and maintained in a program Run Book before programs are released to operational status.

Techn ical Documentation

Instructions for preparation of technical documentation (such as flowcharts) have been covered to some extent in the foregoing sections. Technical documentation includes the following:

• The functional description prepared at the outset of the programming effort

• Fully updated flowcharts used in designing the program

• A fully updated listing of the source code

• Fully corrected source code

• Samples of the input and output

• Main storage dumps and other informative printouts Operator's In struction s

The overall responsibilities of the operator during program processing should be covered in this type of documentation. This material, which can be taken from the Run Book, should provide sufficient information to enable the operator to successfully complete all phases of his responsibilities.

The Run Book

The Run Book is a collection of all documen tation pertaining to each program. It should include all information that will increase understanding of the problem or of the approach chosen for its solution. The effectiveness of the Run Book can be measured by the degree to which persons not associated with the development of the program find its contents readily understandable. The information included in the Run Book should be presented in the sequence dictated by the frequency of its reference. It should be made up of several distinct sections.

Introduction

This section describes in general terms the processing to be performed by this program. It includes the functional specifications of the program and a chart illustrating the processing flow of data from the input files, through the program, to the output files.

Operational Instructions

This section provides all the procedures to be followed when operating the program. Included are program loading, file mounting, and descriptions of any exchanges of messages or signals which take place between the operator and the program. A good basis for these instructions is an operations form similar to the one illustrated in Figure 4-3.

Input/Output Files

The different types of files tha.t can be processed by the program and the data file conven-tions that have been followed ~;hould be described in an introductory paragraph.

Each input and output file should then be described under a separate heading (functional name). A figure might be used to illustrate the file organization and the format of file records. The different types of records which may appear in the file should be listed.

If an input file is to be automatically carried over from another routine, this should be indicated. If input file processing is contingent upon further direction from the programmer staff, the specific conditions should be described.

If an output file is to be automatically forwarded to another routine, this fact should be indicated. If output file processing is contingent upon further direction from the programmer staff, the specific conditions should be set forth. Explain the format of any hard copy output of the program. Provide an example of such outputs. The following topics should be consid-ered:

• Label Records - Indicate whether label records are placed on the file. If they are used, describe label content. Describe the method used to identify each new file to distinguish it from prior output of the same program.

• Data Records - Provide a general description of the data records included on the file.

Indicate record size and the number of records which may be included in a data block.

Describe any control words or other devices which have been included in each data block.

• Rerun/Restart - Explain the rerun/restart capability provided for this file.

5. FILE PREF:JARATION

INTRODUCTION

Installation of a new computer almost always involves file preparation. Even when files used with a previous computer are perfectly compatible with the new system, new files will usually be wanted to take advantage of the higher power of the new system (such as larger main storage or new peripherals) or to apply new work to the computer. As used in this section the term "files" includes, but is not limited to, master files, transaction files, report files, program fil,~s, and tables.

Because the entire data proce.5sing system is based on the files used, file preparation demands careful planning, strict control, and complete auditing. File preparation should be treated as a complete application in itself, receiving the same care as other major appli-cations. The standard development steps of problem definition, information gathering, data analysis, and procedure establishment should be taken.