Documenting a View

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.

1. The primary presentation shows the elements and relationships among them that populate the portion of the view shown in this view packet. The primary presentation should contain the information you wish to convey about the systemin the vocabulary of that viewfirst. It should certainly include the primary elements and relations but under some circumstances might not include all of them. For example, you may wish to show the elements and relations that come into play during normal operation but relegate error handling or exception processing to the supporting documentation. What information you include in the primary presentation may also depend on what notation you use and how conveniently it conveys various kinds of information. A richer notation will tend to enable richer primary presentations. or points to an explanation of the notation used in the presentation.

   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.

   ADVICE

   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.

2. The element catalog details at least those elements depicted in the primary presentation and perhaps others; see the discussion of descriptive completeness in Section 6.1. For instance, if a diagram shows elements A, B, and C, documentation is needed that explains in sufficient detail what A, B, and C are and their purposes or the roles they play, rendered in the vocabulary of the view. In addition, if elements or relations relevant to this view packet were omitted from the primary presentation, they should be is introduced and explained in the catalog. Specific parts of the catalog include
   1. Elements and their properties. This section names each element in the view packet and lists the properties of that element. In Part I, each view we introduced listed a set of properties associated with elements in that view. For example, elements in a module decomposition view have the property of "responsibility"an explanation of each module's role in the systemand elements in a communicating-processes view have timing parameters, among other things, as properties. Whether the properties are generic to the kind of view chosen or the architect has introduced new ones, this is where they are documented and given values.
   2. Relations and their properties. Each view has specific relation type(s) that it depicts among the elements in that view. Mostly, these relations are shown in the primary presentation. However, if the primary presentation does not show all the relations or if there are exceptions to what is depicted in the primary presentation, this is the place to record that information.
   3. Element interfaces. An interface is a boundary across which elements interact or communicate with each other. This section documents element interfaces. An element might occur in more than one view packet or even more than one view. Where its interface is documented is a packaging question, decided on the basis of convenience and addressing the needs of stakeholders. Different aspects of the interface may be captured and documented in different views. Or you may wish to document the interfaces in a single document, in which case this section consists of a pointer.
   4. Element behavior. Some elements have complex interactions with their environment. For purposes of understanding or analysis, it is often incumbent on the architect to specify element behavior.
3. A context diagram shows how the system or portion of the system depicted in this view packet relates to its environment.
4. A variability guide shows how to exercise any variation points that are a part of the architecture shown in this view packet.
5. Architecture background explains why the design reflected in the view packet came to be. The goal of this section is to ex-plain why the design is as it is and to provide a convincing argument that it is sound. Architecture background includes
   1. Rationale. The architect explains why the design decisions reflected in the view packet were made and gives a list of rejected alternatives and why they were rejected. This information will prevent future architects from pursuing dead ends in the face of required changes.
   2. Analysis results. The architect should document the results of analyses that have been conducted, such as the results of performance or security analysis or a list of what would have to change in the face of a particular kind of system modification.
   3. Assumptions. The architect should document any assumptions he or she made when crafting the design. Assumptions are usually about either environment or need. Assumptions about the environment document what the architect assumes is available in the environment and what can be used by the system being designed. Assumptions are also made about invariants in the environment. For example, a navigation system architect might make assumptions about the stability of the earth's geographic and/or magnetic poles. Finally, assumptions about the environment can pertain to the development environment: tool suites available or the skill levels of the implementation teams, for example.

      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.

6. Other information provided will vary according to the standard practices of each organization or the needs of the particular project. If the view packet is maintained as a separate document, you can use this section to record document information (see Section 10.1). Or the architect might record references to specific sections of a requirements document to establish traceability. Information in this section is, strictly speaking, not architectural. Nevertheless, it is convenient to record such information alongside the architecture, and this section is provided for that purpose.
7. Related view packets are the parent, siblings, and any children. In some cases, a view packet's children may reside in a different view, as when an element in one style is decomposed into a set of elements in a different style.

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.

PERSPECTIVES

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.

• Adopt a style guide for the documentation. The style guide will specify such items as fonts, numbering schemes, conventions with respect to acronyms, captions for figures, and other such details. The style guide should also describe how to use the visual conventions discussed in the next several points.
• Use visually distinct forms for emphasis. Word processors offer many techniques for emphasis. Words can be bold, italic, large, or underlined. Using these forms makes some words more important than others.
• Be consistent in using visual styles. Use one visual style for one purpose, and do not mix purposes. That is, the first use of a word might be italicized, and a critical thought might be expressed in bold, but do not use the same style for both purposes, and do not mix styles.
• Do not go overboard with visuals. It is usually sufficient to use one form of visual emphasis without combining them. Is bold less arresting to you than underlined bold? Probably not.
• Try to separate different types of ideas with different visual backgrounds. In this book, we attempted to put the main thread in the body of the book, with ancillary information as sidebars. We also made the sidebars visually distinct so that you would know at a glance whether what you were reading was in the main thread or an ancillary thread.

The key ideas with respect to presentation are consistency and simplicity.

• Use the same visual language to convey the same idea: consistency.
• Do not try to overwhelm the user with visuals; you are documenting a computer system, not writing an interactive novel: shoot for 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.

L.B.

QUOTATION

It may take you months, even years, to draft a single map. It's not just the continents, oceans, mountains, lakes, rivers, and political borders you have to worry about. There's also the cartouche (a decorative box containing printed information, such as the title and the cartographer's name) and an array of other adornmentsdistance scales, compass roses, wind-heads, ships, sea monsters, important personages, characters from the Scriptures, quaint natives, menacing cannibal natives, sexy topless natives, planets, wonders of the ancient world, flora, fauna, rainbows, whirlpools, sphinxes, sirens, cherubs, heraldic emblems, strapwork, rollwork, and/or clusters of fruit.

Miles Harvey, The Island of Lost Maps: A True Story of Cartographic Crime (Random House, 2000, p. 98)