One Document or Several?

You can use the templates in this chapter to create either a single document with separate sections or a series of separate documents, each containing one or more parts of the template. Which option you choose will depend on the size of the system, how you wish to package it for its stakeholders, and your organization's standards and practices. The comprehensive example in Appendix A, for instance, structures the information as a two-volume set.

Document adornments, such as title pages, tables of contents, sign-off approvals, page formats, and the like are important but left largely to your discretion. However, you should make sure that each document you produce contains the following:

• Date of issue and status: draft, baseline, version number, and so on
• Name of issuing organization
• Change history
• Summary

Also make sure that your documentation package includes a glossary of terms, a list of acronyms, and a list of references or at least a pointer to these things in the overall project documentation suite. These items are good things in themselves and will help your documentation be compliant with the recent ANSI / IEEE standard on architecture documentation, which requires them.

PERSPECTIVES

What the Meaning of "Is" Is

Documentation in general, and software architecture documentation in particular, is chock-full of assertions: what the elements are, how they behave, what their interfaces are, and what relationships exist among them. There are assertions about why a design satisfies its requirements, what will change in the future, and, for product line architectures, what must be changed to get a product-ready instance of the architecture. There are assertions about who wrote the documentation, who approved it and when, and where you can find more information. An architecture document is basically a package of bald assertions.

In practice, however, not all assertions are created equal. Information has various pedigrees. Some information represents a constraint that the architect is obliged to honor. Some represents a heuristic that the architect can obey if convenient. Some information simply identifies properties.

When digesting all this information to document an architecture, the architect adds his or her own touch of "assertive freedom." Some of what the architect writes are facts, such as properties; for example, the bandwidth of a chosen network is what it is. Some of what the architect writes are requirements or constraints to be imposed on downstream developers, and no deviation is allowed. An element im-plementer must make sure that the element provides its advertised interface resources, period. Some assertions are nonbinding decisions: suggestions, if you will. Maybe some of those interface resources can be put off until later. Some assertions are placeholders for information not yet available, which is a class unto itself. Some placeholders are clearly marked TBD, but others show desired or possible values. For example, the architect may want to use version 6.4 of a vendor's database, but if it isn't ready by product-ship time, version 6.3 will have to do.

The result is documentation interlaced with insidious ambiguity. The problem is less pronounced in documentation that describes a fielded system rather than prescribes one under development. But even there, the system might not have all the features asserted in the documentation: assertions that were apparently just suggestions, even if the architect didn't think of them as such.

What to do? First, be aware of the problem. Second, for those key assertions whose pedigree is something short of stone tablets carried down a mountain, footnote them with a short explanation about what might cause them to change. It's good discipline to try to do this as you produce the documentation, but you can also make this check part of the documentation review process.

P. C. C.

It depends on what the meaning of the word "is" is. If theif heif "is" means is and never has been, that is one thing. If it means there is none, that was a completely true statement.

William Jefferson Clinton, August 17, 1998