Penny Grubb and Armstrong Takang. Software Maintenance: Concepts and Practice, 2003, pg 7, 239-243.
To understand software maintenance we need to be clear about what is meant by 'software'. It is a common misconception to believe that software is programs. Software comprises not only programs - source code and object code - but also documentation of any facet of the program such as requirements analysis, specification, design, system and user manuals, and the procedures used to setup and operate the software system.
Table 7.1 Types and functions of documentation
User documentation
| 1. System overview | Provides general description of system functions |
| 2. Installation guide | Describes how to set up the system, customize it to local needs, and configure it to particular hardware and other software systems |
| 3. Beginner's guide / tutorial | Provides simple explanations of how to start using the system |
| 4. Reference guide | Provides in-depth description of each system facility and how it can be used |
| 5. Enhancement booklet / release notes | Contains a summary of new features |
| 6. Quick reference card | Serves as a factual lookup |
| 7. System administration | Provides information on services such as networking, security, and upgrading |
System documentation
| 1. System rationale | Describes the objectives of the entire system |
| 2. Requirements analysis / specification | Provides information on the exact requirements for the system as agreed between the stakeholders (user, client, customer, developer). |
| 3. Specification / design | Provides description: (i) of how the system requirements are implemented (ii) of how the system is decomposed into a set of interacting program units (iii) the function of each program unit |
| 4. Implementation | Provide description of: (i) how the detailed system is expressed in some formal programming language (ii) program actions in the form of intra-program comments |
| 5. System test plan | Provides a description of how program units are tested individually and how the whole system is tested after integration |
| 6. Acceptance test plan | Describes the tests the system must pass before the users accept it |
| 7. Data dictionaries | Contains descriptions of all terms that relate to the software system in question |
There are a number of reasons why it is of paramount importance to have accurate and sufficient documentation about a software system:
- To facilitate program comprehension: The function of documentation in the understanding of subsequent modification of the software cannot be overemphasized. Prior to undertaking any software maintenance work, the maintainer should have access to as much information as possible about the whole system.
- To act as a guide to the user: Documentation aimed at users of a system is usually the first contact they have with the system.
- To complement the system Documentation forms an integral part of the entire software system. Without the documentation, there is little assurance that the software satisfies stated requirements or that the organization will be able to maintain it.
The cost of maintaining a software system is proportional to the effectiveness of the documentation which describes what the system does as well as the logic used to accomplish its tasks. To ensure that documentation is up to date, procedures should be put in place to encourage the use of adequate resource for the updating of documents concurrent with system updates.