System Documentation

• System documentation encompasses all of the documents describing the implementation of the system from the requirements specification to the final acceptance test plan:

1. Documents describing the design,
2. Documents describing the implementation,
3. Documents describing testing.

• System documentation is essential for understanding and maintaining a software system.
• The documentation should be

1. structured, and
2. described with overviews leading the reader into more formal and detailed descriptions of each aspect of the system.

• One of the major difficulties with system documentation is the maintenance of consistency across the different documents describing the system. To keep track of changes, it is recommended that documents should be placed under the control of a configuration management system.

Components of the system documentation:

1. The requirements definition and specification and an associated rationale.
2. An overall system specification showing how the requirements are decomposed into a set of interacting programs. This document is not required when the system is implemented using only a single program.
3. For each program in the system, a description of how that program is decomposed into components and a statement of the specification of each component.
4. For each unit, a description of its operation. This need not extend to describing program actions as these should be documented using intra-program comments.
5. A comprehensive test plan describing how each program unit is tested.
6. A test plan showing how integration testing, that is, the testing of all units/programs together is carried out.
7. An acceptance test plan, devised in conjunction with the system user. This should describe the tests which must be satisfied before the system is accepted.