Chapter 10: Software Documentation

Overview

Documentation is the record of the translation from the user's needs to the software that satisfies those needs and instructions for the operation and use of that software.

A vast portion of the software being developed lacks adequate records of how it got where it is. The original requirements are poorly stated, design has just evolved as it went along, code tends to simulate the design rather than implement it, testing is based on showing that the code works rather than that it meets the requirements, and user documentation is incomplete to a fault. The SQS can play a large role in improving this situation.

Documentation is like the markers along a highway. Looking ahead, it provides a trail to follow toward the destination. Looking back, it provides a record of the trip thus far. Each phase of the SDLC prepares the directions for the next phase in the form of some sort of documentation. Those same documents are the record of what has happened during the phase itself. The requirements phase is directed by the statement of needs from the concept exploration phase. The design phase is directed by the requirements document, which is a record of the activities of the requirements phase. In turn, the design documentation directs the coding phase while recording the design phase, and so on. In parallel with the development phases, the testing documentation is prepared, leading to the testing effort the way requirements documentation leads to coding.

Software documentation is composed of management, development, test, and user documentation. It is intended to follow the evolution of the software as it progresses through the SLC.

It is important to note that once a document is written and approved, it can—and must—still change. As development proceeds, errors, defects, incomplete specifications, and necessary additions and deletions will become known. If the documentation is to serve its purpose on a continuing basis, it must be kept current. As discussed in Chapter 6, the documentation must be configuration managed just like the development products themselves. Many software projects have suffered serious problems, not because the documentation was poorly written in the first place, but because it was allowed to fall behind the actual situation as development continued. In the later phases, when it was needed to support testing or maintenance, it was no longer current and, thus, was not useful. The actual, currently approved requirements were no longer reliably documented, the design specification had fallen behind the actual code implementation, and there was no way to accurately trace the code back to the requirements. In almost every case like this, the user winds up with a software system that does something, but not what was actually needed or wanted.

Finally, the documentation is the basis for CM. If the documentation starts out poorly or is allowed to degenerate with respect to the ongoing development activities, the software is out of control. CM loses visibility into what was required and how that has changed. Once the software development effort is out of control, the end result of that development usually is not predictable, verifiable, or maintainable.

Table 10.1 offers recommendations for minimum documentation for various project sizes. Other project factors, such as visibility, criticality, and complexity, will influence the selection of documents each case. (Appendixes A through L include outlines for the primary documents.)

Table 10.1: Software Documentation Recommendations

Project Size

Recommended Documents

Small project

Requirements specification

Design description (as-built design)

Test report

Plans: software development, SQS, CM

Medium project

All small project documents

Preliminary design

Detailed design (build-to design)

Test plan

Large project

All medium project documents

Test cases (and scenarios)

Interface requirements and design

Other documents—not project-size specific

Database requirements and design

User manual

Operations manual

Maintenance plan

Training plan

Risk management plan

Software safety plan



Practical Guide to Software Quality Management
Practical Guide to Software Quality Management (Artech House Computing Library)
ISBN: 1580535275
EAN: 2147483647
Year: 2002
Pages: 137
Authors: John W. Horch

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net