Steve McConnell. Code Complete. Microsoft Press, 1993, pg. 453.
Most programmers enjoy writing documentation if the documentation standards aren't unreasonable. Like layout, good documentation is a sign of the professional pride a programmer puts into a program.
Mike Punter. "Programming for Maintenance" in Techniques of Program and System Maintenance. QED Information Sciences, 1988, pg. 116.
- Sooner or later someone else is going to have to understand the programs you write.
- Programs must be written for people as well as computers.
- Knowing that a program can be understood and amended by someone else ought to be one of the programmer's criteria for success.
Robert Riggs. "Computer Systems Maintenance" in Techniques of Program and System Maintenance. QED Information Sciences, 1988, pg. 145.
I mention good documentation as the first requirement because of its overriding importance. If you run a sloppy systems and programming shop, you might as well forget the organization and management of a systems maintenance group and just hope that the authors stay around. In fact, a very high percentage of production programs must be maintained by a programmer other than the original author. Failure to complete good documentation puts you in a vicious, never ending circle of crises.
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.
Tom DeMarco. Why Does Software Cost So Much? Dorset House, 1995, pg. 173-178.
There are two familiar variants of the documentation problem: a) you write all the internal documentation that you know you need and you pay a terrible price for it, or b) you don't write all the internal documentation you need and you pay a terrible price for that.
The first variant occurs in companies that have a strong commitment to the conventional wisdom of software construction. They respect, as an article of faith, the maxim: "The job is not over until the paperwork is done." But the costs of paper documentation of program products can be daunting. ... The costs of not documenting program internals are less well quantified, but most development managers believe that missing and inadequate internal documentation are major contributors to the staggering cost of software maintenance.
In early 1988, Aldus Engineering's Product Adaptation group embarked on an experiment in documenting program internals on video. The perception was that this medium had a lower drudgery factor for those who had to produce the documentation, and a lower total cost. Proof of the first of these points was the enthusiasm the idea provoked among those who were asked to participate. ... The initial videos were planned as five afternoon filming sessions, covering data structures, display issues, screen dynamics, event handling, and portability concerns. ... In an informal assessment, viewers of the videos provided positive feedback.
Mira Kajko-Mattsson. "The State of Documentation Practice within Corrective Maintenance". Proceedings of the IEEE International Conference on Software Maintenance, ICSM 2001, pg. 354-363.
Consistent, correct and complete documentation is an important vehicle for the maintainer to gain understanding of a software system, to ease the learning and/or relearning processes, and to make the system more maintainable. ... For this purpose, we have defined a set of documentation requirements. These requirements have been satisfactorily implemented to the following extent: 53% of the organizations studied deliver complete and consistent system documentation to the maintenance phase. Only 16% of the organizations studied update their software system documents at all granularity levels. 53% of the organizations studied have their user manuals consistent with the state of their software systems. 42% of the organizations studied revise and modify their regression test case repositories. 11% of the organizations studied have achieved full traceability amongst their system documents, and only 5% have achieved full traceability of change. 21% of the organizations studied provide guidelines for how to write system documentation. 42% of the organizations studied define and follow guidelines for internal software code documentation. 26% of the organizations studied provide a checklist of all document types required for executing and supporting the corrective maintenance process. In only 21% of the organizations studied, the corrective maintenance process explicitly states where in the process each type of documentation should be updated/checked. 26% of the organizations studied have a formal approval of the quality of system documentation after each corrective change. 37% of the organizations studied periodically check the quality of their system documentation. 32% of the organizations update their documentation as soon as some inconsistency is discovered. 74% of the organizations studied have access to system development documentation, but only 16% of the organizations have access to system development journal. 68% of the organizations studied record all changes to their software systems. When studying this requirement, we have observed that there are still organizations communicating software problems and changes orally. 32% of the organizations studied keep history of the reported software problems for their software components. 21% of the organizations studied actively update a formal system maintenance journal. None of the organizations studied gives some form of education in written proficiency in order to improve the quality of system documentation.
Timothy Lethbridge, Janice Singer, Andrew Forward. "How Software Engineers Use Documentation: The State of the Practice". IEEE Software, November 2003, pg 35-39.
Percentage of survey respondents who rated documentation effective or extremely effective for particular tasks: learning a software system (61%), testing a software system (58%), working with a new software system (54%), solving problems when other developers are unable to answer questions (50%), looking for big-picture information about a software system (46%), maintaining a software system (35%), answering questions about a system for management or customers (33%), looking for in-depth information about a software system (32%), and working with an established software system (32%).
Our results indicate that software engineers create and use simple yet powerful documentation, and tend to ignore complex and time-consuming documentation.
Harvey Siy and Lawernce Votta. "Does the Modern Code Inspection Have Value?". Proceedings of the IEEE International Conference on Software Maintenance, ICSM 2001, pg. 281.
For years, it was believed that the value of inspections is in finding and fixing defects early in the development process. Otherwise, the cost to find and fix them later is much higher. However, in examining code inspection data, we are finding that inspections are beneficial for an additional reason. They make code easier to understand and change. An analysis of data from recent code inspection experiments shows that 60% of all issues raised in the code inspections are not problems that could have been uncovered by latter phases of testing or field usage because they have little or nothing to do with the visible execution behavior of the software. Rather, they improve the maintainability of the code by making the code conform to coding standards, minimizing redundancies, improving language proficiency, improving safety and portability, and raising the quality of documentation. We conclude that even if advances in software technology have diminished the value of inspections as a defect detection tool, in most cases, it continues to be of value as a maintenance tool.