The mythical Man-Month: Chapter 6 Passing the Word

1. The mythical Man-Month: Chapter 6Passing the Word Presented by Collin Kanaley

2. 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.

3. 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.

4. 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.

5. 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.

6. 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.

7. 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.

8. Conferences and Courts

9. 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.

10. 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.

11. 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.

12. 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.

13. 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.