A PROGRAM DOCUMENTATION TOOL
Original Publication Date: 1992-Dec-01
Included in the Prior Art Database: 2002-Jan-23
AbstractFitly to seventy percent of the cost of software is spent after the product is initially delivered. This stage of the software development, usually called "mainte- nance: can consume as much as eighty percent of a team's resources after only three products have been delivered. With this level of resources dedicated to maintaining old products, new projects either take far too long to be delivered, or are not even attempted.
MOIOROlA INC. Technical Developments Volume 17 December 1992
A PROGRAM DOCUMENTATION TOOL
by Robert Turner
Fitly to seventy percent of the cost of software is spent after the product is initially delivered. This stage of the software development, usually called "mainte- nance: can consume as much as eighty percent of a team's resources after only three products have been delivered. With this level of resources dedicated to maintaining old products, new projects either take far too long to be delivered, or are not even attempted.
To install changes in a program, or maintain it, a certain amount of understanding about the problem to be solved, i.e. domain knowledge, and some knowledge about the implementation, i.e. software, is required. As the developer of the software works on other projects the domain and implementation knowledge of prior proj- ects will be forgotten. This causes the cost of mainte- nance to increase. The problem of software maintenance is also exacerbated by the development programmer sometimes being someone other than the maintenance programmer. The domain knowledge and the implemen- tation knowledge must be transferred from the devel- oper to the maintainer.
One way to refresh the developer's memory or to transfer the domain and implementation knowledge to another person is documentation. Documentation is the written record of the problem definition and implemen- tation. As sotlware developers strive to reuse others' software and to produce higher levels of quality, they must create accurate, consistent, and understandable documentation.
However, documentation does have limitations. As the program changes over time the documentation must also be changed. Inaccurate or out of date documenta- tion confuses or misdirects the maintenance program- mer causing inaccurate moditications and schedule over- runs. The cliche about documentation is, "Wrong documentation is worse than no documentation? His- torically, development programmers did not create high quality documentation and maintenance programmers
0 Motorola. 1°C. ,992
did not update what little documentation existed.
This paper describes a technique to improve the way program documentation is created and maintained.
In most cases the program documentation was kept in separate files. These distinct tiles were usually located in diierent directories and in some cases on different machines than the source or program fdes. Having the documentation in a diierent place than the actual source code caused problems for the programmer. Often these distinct tiles required the programmer to use a diierent set of tools to edit or update the documentation tiles. Because the programmer viewed editing the documen- tation as inconvenient, the documentation was updated if and when the programmer got a chance. In many cases the style of the documentation was left to the dis- cretion of the programmer. This lead to an inconsistent style and an inc...