P.6. Seven Rules for Sound Documentation

Architecture documentation is much like the documentation we write in other facets of our software development projects. As such, it obeys the same fundamental rules for what distinguishes good, usable documentation from poor, ignored documentation.

P.6.1 Rule 1: Write Documentation from the Reader's Point of View

Seemingly obvious but surprisingly seldom considered, this rule offers the following advantages.

• A document is written approximately oncea little more often if you count the time for revisionsbut if useful will be read many scores of times. Therefore, the document's "efficiency" is optimized if we make things easier for the reader. Edsger Dijkstra, the inventor of many of the software engineering principles we now take for granted, once said that he would happily spend two hours pondering how to make a single sentence clearer. He reasoned that if the paper were read by a couple of hundred peoplea decidedly modest estimate for someone of Dijkstra's caliberand he could save each reader a minute or two of confusion, it was well worth the effort. Professor Dijkstra's consideration for the reader reflects his classic manners, which brings us to the second advantage.
• Writing for the reader is polite. A reader who feels that the document was written with him or her in mind appreciates the effort but, more to the point, will come back to the document again and again in the future, which brings us to the third advantage.
• Documents written for the reader will be read; documents written for the convenience of the writer will not. Similarly, we like to shop at stores that seem to want our business and to avoid stores that do not.
• Avoid unnecessary insider jargon. The documentation may be read by someone new to the field or from a company that does not share the same jargon.

In the realm of software documentation, documents written for the writer often take one of two forms: stream of consciousness or stream of execution. Stream-of-consciousness writing captures thoughts in the order in which they occurred to the writer and lacks an organization that is helpful to a reader. Avoid stream-of-consciousness writing by making sure that you know what question(s) are being answered by each section of a document; that is, architect your documentation.

Stream-of-execution writing captures thoughts in the order in which they occur during the execution of a software program. For certain kinds of software documentation, this is entirely appropriate, but it should never be given as the whole story.

P.6.2 Rule 2: Avoid Unnecessary Repetition

Each kind of information should be recorded in exactly one place. This makes documentation easier to use and much easier to change as it evolves. It also avoids confusion; information that is repeated is likely to be in a slightly different form, and now the reader must wonder: Was the difference intentional? If so, what is the meaning of the difference?

Now, expressing the same idea in different forms is often useful for achieving a thorough understanding. However, it should be a goal that information never, or almost never, be repeated verbatim unless the cost to the reader of keeping related information separate is high. Locality of information reference is important; unnecessary page flipping leads to reader dissatisfaction. Also, two different views might have repetitive information for clarity or to make different points. If keeping the information separate proves too high a cost to the reader, repeat the information.

P.6.3 Rule 3: Avoid Ambiguity

A primary reason architecture is useful is that it suppresses or defers the plethora of details that are necessary to resolve before bringing a system to the field. The architecture is therefore ambiguous, one might argue, with respect to these suppressed details. Even though an architecture may be brought to fruition by any number of elaborations/implementations, as long as those implementations comply with the architecture, they are all correct. Unplanned ambiguity occurs when documentation can be interpreted in more than one way and at least one of those ways is incorrect. The documentation should be sufficient to avoid multiple interpretations.

A well-defined notation with precise semantics goes a long way toward eliminating whole classes of linguistic ambiguity from a document. This is one area where architecture description languages help a great deal, but using a formal language isn't always necessary. Simply adopting a set of notational conventions and then avoiding unplanned repetition, especially the "almost-alike" repetition mentioned previously, will help eliminate whole classes of ambiguity. But if you do adopt a notation, then the following corollary applies:

3a. Explain Your Notation

The ubiquitous box-and-line diagrams that people always draw on whiteboards are one of the greatest sources of ambiguity in architecture documentation. Although not a bad starting point, these diagrams are certainly not good architecture documentation. For one thing, the behavior of the elements, a crucial part of the architecture, is not defined. Furthermore, most such diagrams suffer from ambiguity. Are the boxes supposed to be modules, objects, classes, processes, functions, procedures, processors, or something else? Do the arrows mean submodule, inheritance, synchronization, exclusion, calls, uses, data flow, processor migration, or something else?

Make it as easy as possible for your reader to determine the meaning of the notation. If you're using a standard visual language defined elsewhere, refer readers to the source of the language's semantics. (Even if the language is standard or widely used, different versions often exist. Let your reader know, by citation, which one you're using.) For a home-grown notation, include a key to the symbology. This is good practice because it compels you to understand what the pieces of your system are and how they relate to one another and it is also courteous to your readers.

P.6.4 Rule 4: Use a Standard Organization

Establish a standard, planned organization scheme; make your documents adhere to it; and ensure that readers know about it. A standard organization offers many benefits.

• It helps the reader navigate the document and find specific information quickly. Thus, this benefit is also related to the write-for-the-reader rule.
• It also helps the document writer plan and organize the contents and reveals what work remains to be done by the number of sections labeled TBD (to be determined).
• It embodies completeness rules for the information; the sections of the document constitute the set of important aspects that need to be conveyed. Hence, the standard organization can form the basis for a first-order validation check of the document at review time.

Corollaries are

1. Organize documentation for ease of reference. Software documentation may be read from cover to cover at most once, probably never. But a document is likely to be referenced hundreds or thousands of times.
2. Mark as TBD what you don't yet know rather than leaving it blank. Many times, we can't fill in a document completely because we don't yet know the information or because decisions have not been made. In that case, mark the document accordingly rather than leave the section blank. If the section is blank, the reader will wonder whether the information is coming or whether a mistake was made.

P.6.5 Rule 5: Record Rationale

When you document the results of decisions, record the alternatives you rejected and state why. Later, when those decisions come under scrutiny or pressure to change, you will find yourself revisiting the same arguments and wondering why you didn't take another path. Recording your rationale will save you enormous time in the long run, although it requires discipline to record your rationale in the heat of the moment.

P.6.6 Rule 6: Keep Documentation Current But Not Too Current

Documentation that is incomplete or out-of-date does not reflect truth, does not obey its own rules for form and internal consistency, and is not used. Documentation that is kept current and accurate is used. Why? Because questions about the software can be most easily and most efficiently answered by referring to the appropriate document. Documentation that is somehow inadequate to answer the question needs to be fixed. Updating it and then referring the questioner to it will deliver a strong message that the documentation is the final, authoritative source for information.

During the design process, on the other hand, decisions are made and reconsidered with great frequency. Revising documentation to reflect decisions that will not persist is an unnecessary expense.

Your development plan should specify particular points at which the documentation is brought up-to-date or the process for keeping the documentation current. Every design decision should not be recorded the instant it is made; rather, the document should be subject to version control and have a release strategy, just as every other artifact being produced does.

P.6.7 Rule 7: Review Documentation for Fitness of Purpose

Only the intended users of a document will be able to tell you whether it contains the right information presented in the right way. Enlist their aid. Before a document is released, have it reviewed by representatives of the community or communities for which it was written.