THE MYTHICAL MAN-MONTH: CHAPTER 6

PASSING THE WORDPresented by Collin Kanaley

Written Specifications – The Manual

The manual is a necessary tool, but not a sufficient one. The manual is the chief product of the

architect. It should describe everything the user sees,

while refraining from describing what they do not see.

While containing the ideas of many, the manual should be written by only one or two individuals, in order to maintain consistency.

Definitions Definitions should repeat all the

essentials and agree with each other. Precision is more important than a lively read.

English, or any other human language, is not naturally a precision instrument for definitions. Because of this, the manual writer must strain himself to achieve the necessary precision. As a result, an attractive alternative is to use a formal notation for such definitions.

Formal Definitions Formal Definition Pros:

Formal Definitions are precise. They tend to be complete.

Formal Definition Cons: Formal Definitions tend to lack

comprehensibility. Often, prose explanations are necessary to

make their content easy to learn and teach. Therefore, it is likely future specifications

will consists of both a formal definition and a prose definition.

Formal definitions tend to describe an implementation of the hardware or software system whose externals they are prescribing.

Advantages of using an implementation as a definition: All questions can be settled unambiguously by

experiment. Debate is never needed, so answers are quick. Answers are always as precise as one wants, and

are always correct, by definition. Disadvantages of using an implementation as

a definition : The implementation may over-prescribe the

externals. In an unpoliced system all kinds of side effects may

occur.

However, the use of an implementation as a formal definition may result in confusion as to whether the prose description or the formal description is actually the standard.

This is particularly true of programmed simulations.

One must refrain from modifying the implementation while it is serving as the standard.

Direct Incorporation

This technique disseminates and enforces definitions.

It is to design the declaration of the passed parameters or shared storage, and to require the implementations to include that declaration via compile-time operation.

Conferences and Courts

Conferences and Courts

Meetings are necessary. The hundreds of man-to-man consultations

must be supplemented by larger, more formal gatherings.

It is recommended that there be weekly, half-day conferences of all the architects, plus representatives for the hardware and software implementers, and market planners. The emphasis is on creativity, not merely

discussion. Decisions from these weekly conferences give

quick results and allow work to proceed.

In order to settle some decisions, or to address previously unforeseen problems, biannual “supreme court” sessions, typically lasting two weeks, should be held. Everyone participates and is heard.

Multiple Implementations In most computer projects there comes a

day when the manual and the machine do not agree. Typically the manual is changed instead of the

machine being changed. However, when there are multiple

implementations, the delays and costs associated with fixing the errant machine can be overmatched by the delays and costs in revising the machines that followed the manual faithfully.

The Telephone Log

Upon encountering something of question, a puzzled implementer should be encouraged to contact the responsible architect and ask his question, rather than guess and proceed.

One useful mechanism is a telephone log kept by the architect, in which he records every question he is asked and every answer.

Each week the logs of several architects are concatenated, reproduced, and distributed to the users and implementers.

Product Test

An independent product-testing organization should be both the project manager’s best friend and his daily adversary. This group serves as a devil’s advocate,

searching for defects and pinpointing areas of conceivable defeat.

The product-testers serve as surrogate customers.

In real use, every flaw will eventually show.