Recall from Section 6.1 that a view consists of a set of view packets that are related by sibling and parent/child relationships. Documenting a view, then, becomes a matter of documenting a series of view packets. No matter what the view, the documentation for a view packet can be placed into a standard organization consisting of seven parts.
The primary presentation is usually graphical. If so, this presentation must be accompanied by a key that explains
Sometimes, the primary presentation can be textual, as we saw in Figure 2.2 on page 58. If the primary presentation is textual instead of graphical, it still carries the obligation to present a terse summary of the most important information in the view packet. If that text is presented according to certain stylistic rules, they should be stated or incorporated by reference, as the analog to the graphical notation key.
Every diagram in the architecture documentation should include a key that explains the meaning of every symbol used. The first part of the key should identify the notation. If a defined notation is being used, the key should name it and cite the document that defines the version being used. Otherwise, the key should define the symbology and the meaning, if any, of colors, position, or other information-carrying aspects of the diagram.
Assumptions about need state why the design provided is sufficient for what's needed. For example, if a navigation system's software interface provides location information in a single geographic frame of reference, the architect is assuming that it is sufficient and that alternative frames of reference are not useful.
Assumptions can play a crucial role in the validation of an architecture. The design that an architect produces is a function of these assumptions, and writing them down explicitly makes it vastly easier to review them for accuracy and soundness than trying to ferret them out by examining the design.
Items 27, the supporting documentation, explain and elaborate the information in the primary presentation. Even if some items are empty for a given view packetfor example, perhaps no mechanisms for variability exist or no relations other than those shown in the primary presentation existinclude those sections, marked "none." Don't omit them, or your reader may wonder whether it was an oversight.
Every view packet, then, consists of a primary presentation, usually graphical, and supporting documentation that explains and elaborates the pictures (see Figure 10.1). To underscore the complementary nature of the primary presentation with its supporting documentation, we call the graphical portion of the view packet an architectural cartoon. We use the definition from the world of fine art: A cartoon is a preliminary sketch of the final work; it is meant to remind us that the picture, although getting most of the attention, is not the complete description but only a sketch of it. In fact, it may be considered merely an introduction to or a quick summary of the information provided by the supporting documentation.
Figure 10.1. Documenting a view packet consists of documenting seven parts: (1) the primary presentation; (2) the element catalog; (3) a context diagram; (4) a variability guide; (5) architecture background, including rationale, results of analysis, and assumptions made; (6) organization- or project-specific information; and (7) pointers to the view packet's siblings, parent(s), or children. If the primary presentation is graphical, we call it a cartoon. A cartoon must be accompanied by a key that explains the notational symbology used or that points to the place where the notation is explained.
Presentation Is Also Important
Throughout this book, we focus on telling you what to document. We do not spend much, if any, time on how it should look, although this is not because form is unimportant. Just as the best-designed algorithm can be made to run slowly by insufficient attention to detail during coding, so too the best-designed documentation can be made difficult to read by insufficient attention to presentation details. By presentation details, I mean such items as style of writing, fonts, types and consistency of visual emphasis, and the segmenting of information.
We have not spent time on these issues not because we do not think they are important but because presentation details are not our field of expertise. Universities offer master's degrees in technical communication, in information design, and in other fields related to the presentation of material. We have been busy being software engineers and architects and have never been trained in presentation issues. Having denied expertise, however, I am now free to give some rules of thumb.
The key ideas with respect to presentation are consistency and simplicity.
The goal of the architecture documentation, as we have stressed throughout this book, is to communicate the basic concepts of the system clearly to the reader. Using simple and consistent visual and stylistic rules is an important aspect of achieving this goal.