Program Documentation
Program documentation consists of a set of notes, diagrams, etc., which accompany a program to help with its implementation.
REASONS FOR PRODUCING DOCUMENTATION
1 To enable the people designing and writing the program to work together.
2 To explain to the user of the program what to do.
3 To help people responsible for maintaining or modifying the program.
Documentation is usually in two distinct parts:
1 Documentation for users of the program.
2 Technical documentation for use by programmers.
DOCUMENTATION FOR THE USER
This usually contains information about:
1 Background-an explanation of the system that the program is designed to work within.
2 What the program does:
(a) What problems the program solves and its role in the system.
(b) What options it offers the user.
(c) Limitations of the program-what it will not do.
3 The computing requirements-what hardware and software are necessary to run it successfully.
4 How to collect and prepare data for the program. If this involves special documents there will be instructions on how to fill them in.
5 How to operate the program. For a batch program the system control cards necessary to get it to run. For an interactive program there will also be details of the conversation when it is run.
6 How to interpret the output.
Note: the user documentation for a software package is called a User Manual.
DOCUMENTATION FOR A PROGRAMMER
This documentation may be used by:
1 The programmer who wrote the program, or
2 People working with the programmer, such as the systems analyst and the programmer’s supervisor, or
3 A programmer responsible for maintaining or modifying the program.
The documentation would usually include:
1 A system flowchart with annotation
2 Program flowcharts with annotation
3 Technical details of any limitations, special features, different versions, etc.
4 A program listing accompanied by a list of the variables used in the program and an explanation of their purpose.
5 Details of data structures used-e.g. files and arrays.
6 A set of test data and expected output with which to check that the program operates successfully.