STEP 2: DOCUMENT THE DESIGN
At this point it is appropriate to raise the issue of - "how much documentation?" My own view is "quite a lot;" certainly more than most programmers, analysts, or program designers are willing to do if left to their own devices.
The first rule of managing software development is ruthless enforcement of documentation requirements.
Occasionally I am called upon to review the progress of other software design efforts.
My first step is to investigate the state of the documentation.
If the documentation is in serious default my first recommendation is simple.
Replace project management.
Stop all activities not related to documentation.
Bring the documentation up to acceptable standards.
Management of software is simply impossible without a very high degree of documentation.
As an example, let me offer the following estimates for comparison.
In order to procure a 5 million dollar hardware device, I would expect that a 30 page specification would provide adequate detail to control the procurement.
In order to procure 5 million dollars of software I would estimate a 1000 page specification is about right in order to achieve comparable control.
Why so much documentation?
- Each designer must communicate with interfacing designers, with his management and possibly with the customer. A verbal record is too intangible to provide an adequate basis for an interface or management decision. An acceptable written description forces the designer to take an unequivocal position and provide tangible evidence of completion. It prevents the designer from hiding behind the - "I am 90-percent finished" - syndrome month after month.
- During the early phase of software development the documentation is the specification and is the design. Until coding begins these three nouns (documentation, specification, design) denote a single thing. If the documentation is bad the design is bad. If the documentation does not yet exist there is as yet no design, only people thinking and talking about the design which is of some value, but not much.
- The real monetary value of good documentation begins downstream in the development process during the testing phase and continues through operations and redesign. The value of documentation can be described in terms of three concrete, tangible situations that every program manager faces.
- During the testing phase, with good documentation the manager can concentrate personnel on the mistakes in the program. Without good documentation every mistake, large or small, is analyzed by one man who probably made the mistake in the first place because he is the only man who understands the program area.
- During the operational phase, with good documentation the manager can use operation-oriented personnel to operate the program and to do a better job, cheaper. Without good documentation the software must be operated by those who built it. Generally these people are relatively disinterested in operations and do not do as effective a job as operations-oriented personnel. It should be pointed out in this connection that in an operational situation, if there is some hangup the software is always blamed first. In order either to absolve the software or to fix the blame, the software documentation must speak clearly.
- Following initial operations, when system improvements are in order, good documentation permits effective redesign, updating, and retrofitting in the field. If documentation does not exist, generally the entire existing framework of operating software must be junked, even for relatively modest changes.
Figure 6 shows a documentation plan which is keyed to the steps previously shown.
Note that six documents are produced, and at the time of delivery of the final product, Documents No.1, No.3, No.4, No.5, and No.6 are updated and current.