Excerpted from Systems Architecting, Creating and Building Complex Systems, Eberhardt Rechtin, Prentice Hall, 1991.

MANAGERIAL RESPONSE III: WELL-ARCHITECTED DOCUMENTATION

Demanding ultraquality in a system is something like demanding a perfect budget proposal. There are so many things to be accounted for that it seems as if getting everything right is hopeless. There are always changes at the last minute, and always issues that cannot be resolved.

Comptrollers, however, have learned that it is a hopeless and unnecessary objective to have budgets and accounts be "right." It is only necessary that they be complete, internally consistent, precise, traceable, and authoritative. Assumptions may or may not be correct, but they can be clearly and explicitly stated. Only then can budgets and accounts provide solid baselines from which disciplined changes can be made. Only then can they be trusted to be as remarkably error-free as they are.

Much the same applies to ultraquality systems. Unless the system's documentation is solid and disciplined, widely distributed and understood, it cannot be free of error. The reason is easy enough. People must not only be informed, they must be completely, consistently, precisely, etc., informed, because:

• Unless everyone who needs to know **does**** know, somebody somewhere will foul up.**

The foul-ups are almost always inadvertent. Many are the result of well-intended "improvements." Some are errors of commission; many are omission. Lacking authoritative information on how things should be done, people will do the best that they know how. And it may be quite wrong. It can be as simple as cleaning a part with the wrong solvent or using an unauthorized symbol in a line of computer code.

Documents — policies, procedures, reports, memoranda, equipment pedigrees, military specifications (MILSPECS), electronic data bases, drawings, software programs, and the like — are the memory and lifeblood of a complex system. Handshakes, verbal agreements, and private understandings its nemesis.

Well-architected documents do the following:

• Directly benefit the writers just in the process of writing them

• Define requirements, design characteristics, critical parameters, interfaces, tests, acceptance criteria, schedules and operational responsibilities

• Establish critical "paper trails" of component histories, FMEAs, prior performance, past anomalies, process changes, and decisions

• Control both the build process and the configuration of the system

• Establish well-reasoned operational procedures

• Form the foundation for future, more complex systems.

In the simplest of systems, a few individuals, writing "on the back of envelopes'' and running the project "out of their hip pockets," could achieve success. In complex systems—those worth more than a few hundred thousand dollars each—there are too many variables, too many interrelationships, too much embedded corporate memory, and too high a demand for quality to take the risks of human fallibility. A manufacturer ignores or discards system documentation at considerable risk. An operator modifies them only for good and sufficient reason.

Example:

In the early 1970s, the Air Force did an interesting experiment. It sent out a Request for Proposal for a prototype of a new combat aircraft with the explicit provision that the bidders need not use MILSPECs and other similar documents; good "industry practice" would suffice. The bidders, however, would have to say what practice they would use. All bidders, without exception, elected to use government documentation. There was no substitute for what that documentation performed. Indeed, there was no “industry practice” sufficiently documented to be usable.

Example:

It is not unusual in doing final testing to come across an anomaly. When that happens under pressure to meet a deadline, the temptation can be strong to deviate from established test procedures. There are reasons for those procedures, and for not doing others, that are too easily forgotten. The risks are considerable that more harm will be done than good.

Few would argue with the principle that good documentation is essential for complex systems. The argument is over what kind and how much is required for ultraquality systems. Ideally, it should be complete without being voluminous; as error-free and fault-tolerant as the system it supports, easily modified but under tight configuration control, inexpensive, up to date, and readily accessed. This is a tall order.

The present situation is far from ideal. Few if any of the ideal characteristics exist today, much less exist as an integrated set. The rationale for many decision documents is seldom part of the document; so documents stay in effect after the conditions that established them have changed - making the document obsolete, but providing no procedural way of justifying a change. Documents refer to supporting documents to the point where hundreds of documents may have to be reviewed in order to change any one of them. "Tailoring," or the modification of specifications to better suit a particular system, is encouraged but seldom proposed, because the confidence in predicting the technical and financial effects of the changes is so low.

It is fair to say that documentation is expensive, time consuming, inefficient, far from error-free, distrusted, and generally unpopular. A common plea is to get rid of as much of it as possible.

The solution is not to call for its reduction, but to improve its quality. That means the right choice of events and parameters to document. It means improved methods of data-base management for document entry, control, and access. It means timely document review and maintenance. It means that the architect must recognize and act on the fact that

Ultraquality systems and processes demand ultraquality documentation-complete but concise and error-free.

The challenge of ultraquality documentation is as difficult to meet as that of any element of the system. It is already confounding software developers, integrated-circuit manufacturers, manned flight system architects, and government procurement officials.