In many ways, an architecture is to a system what a map of the world is to the world. Thus far, we have focused on capturing the various architectural views of a system, which tell the main story. In the words of Miles Harvey, they are the "continents, oceans, mountains, lakes, rivers, and political borders" of the complete system map that we are drawing. But we now turn to the complement of view documentation, which is capturing the information that applies to more than one view or to the documentation package as a whole. Documentation beyond views corresponds to the adornments of the map, which complete the story and without which the work is inadequate.
Documentation beyond views consists of three major aspects, which we can summarize as how/what/why:
Figure 10.2 summarizes documentation beyond views.
Figure 10.2. Documenting information beyond views consists of how/what/why: how the documentation is laid out to serve stakeholdersa documentation roadmap and a view template; additional information beyond the views about what the architecture issystem overview, mapping between views, a directory, and a glossary; and why the architecture is the way it issystem background, design constraints, and rationale.
10.3.1 How the Documentation Is Organized to Serve a Stakeholder
Every suite of architecture documentation needs an introductory piece to explain its organization to a new stakeholder and to help that stakeholder access the information he or she is most interested in. The two kinds of how information to help an architecture stakeholder are a documentation roadmap and a view template.
The documentation roadmap introduces the reader to the information that the architect has chosen to include in the suite of documentation. When using the documentation as a basis for communication, a new reader needs to determine where particular information can be found. When using the documentation as a basis for analysis, a reader needs to know which views contain the information necessary for a particular analysis. A roadmap contains this information.
A roadmap consists of the following two sections:
 ANSI/IEEE-1471-2000, the ANSI/IEEE recommended practice for architectural description for software-intensive systems, requires that the se-lected views address the concerns of at least users, acquirers, developers, and maintainers. See Section 11.6 for more information.
Use the organization shown in Figure 10.1 as the basis for your view template. Modify it as necessary to make it appropriate for your organization's standards and the special needs of the development project at hand. Be cautious about throwing out sections that you think you don't need; the presence of a section in the template can prod you to think about the issue across the system, whereas omitting the section will let you forget about it, perhaps to the detriment of the system. For each section, include a terse description of the contents of that section. It is possible, but unlikely, that different views will have different templates. If so, produce a view template for each case necessary, and note in each view the template it follows.
 This information is also required by ANSI/IEEE-1471-2000.
Figure 10.3 shows what a roadmap might say about a layered view for system S.
Figure 10.3. A roadmap for a layered view of system S
A view template is the standard organization for a view. Figure 10.1 and the material surrounding it provide a basis for a view template by defining the standard parts of a view document and the contents and rules for each part. The purpose of a view template is that of any standard organization: It helps a reader navigate quickly to a section of interest, and it helps a writer organize the information and establish criteria for knowing how much work is left to do.
10.3.2 What the Architecture Is
This is a short prose description of the system's function, its users, and any important background or constraints. The purpose is to provide readers with a consistent mental model of the system and its purpose.
The system overview is, strictly speaking, not part of the architecture and does not contain architectural information but is indispensable for understanding the architecture. If an adequate system overview exists elsewhere, such as in the overall project documentation, a pointer to it is sufficient.
Mapping Between Views
Because all the views of an architecture describe the same system, it stands to reason that any two views will have much in common. Helping a reader or other consumer of the documentation understand the relationship between views will help that reader gain a powerful insight into how the architecture works as a unified conceptual whole. Being clear about the relationship by providing mappings between views is the key to increasing understanding and to decreasing confusion.
The mappings in a particular architecture are often complicated. For instance, each module may map to multiple runtime elements, such as when classes map to objects. Complications arise when the mappings are not one-to-one or when runtime elements of the system do not exist as code elements at all, such as when they are imported at runtime or incorporated at build or load time. These are relatively simple none- or one-to-many mappings. But in general, parts of the elements in one view can map to parts of elements in another view.
Documenting the Mapping Between Views
To document a mapping from one view to another, use a table that lists the elements of the first view in some convenient look-up order. For each element
The table itself should be annotated or introduced with an explanation of the mapping that it depicts; that is, what the correspondence is between the elements across the two views. Examples include is implemented by for mapping from a component-and-connector view to a module view, implements for mapping from a module view to a component-and-connector view, included in for mapping from a decomposition view to a layered view, and many others.
For which views should you provide a mapping? The answer, of course, is that it depends, but begin with these rules of thumb:
As discussed in Section 6.1, a view packet can sometimes point to another view packet in a different view. This is also part of the information that maps views.
The directory is an index of all the elements, relations, and properties that appear in any of the views, along with a pointer to its definition.
Glossary and Acronym List
The glossary and acronym list defines terms used in the architecture documentation that have special meaning. These lists, if they exist as part of the overall system or project documentation, may be given as pointers in the architecture package.
10.3.3 Why the Architecture Is the Way It Is: Background, Design Constraints, and Rationale
This section documents the reasoning behind decisions that apply to more than one view. Prime candidates include documentation of background or organizational constraints that led to decisions of systemwide import.
By now, you may realize that rationale is an important ingredient in the mix of architecture documentation, for this is the third place in the documentation package where it enjoys a reserved section. (The first place is in the documentation for an interface, see Chapter 7, and a second is in the template for a view, shown in Figure 10.1.) Having three places in the documentation package for rationale does indeed signal its importance but also results from the fact that these are different kinds of rationale, distinguished by the scope of the design decisions to which each pertains. Rationale can apply to a single view, to the design of an interface of an individual element, or to the entire design approach. No matter what the scope, the principles about what rationale should contain and when it should be included overlap all areas.
Rationale is the architect's chance to explain key decisions to a skeptical audience of peers, perhaps even a future architect. The goal is to convey why the architectureor the piece of it to which the rationale appliesis in fact a good solution. The idea is to convey a vicarious appreciation of the thought process the architect went through to arrive at the decision.
Which Decisions to Justify
Which of the hundreds or thousands of design decisions comprising an architecture should be accompanied by rationale explaining them? Certainly not all of them. It's simply too time consuming, and many decisions do not warrant the effort. So how do you select which decisions are important enough to warrant documentation of rationale? Document the rationale behind a design decision in the following circumstances:
Once you've decided to document a design decision, try to describe it with the following five-part outline:
Like all documentation, rationale is subject to a cost/benefit equation. But know this: Most rationale is read and used by the person who wrote it in the first place, often after weeks rather than years. So if you're altruistic, write rationale as your legacy for the next generation. If you're more motivated by interests closer to home, remember that the time it saves may be your own.
Building an Architecture Overview Presentation
Sooner or later, every architect has to give an oral overview of an architecture, backed up by viewgraphs. Once built, the presentation is likely to be used often, introducing the architecture to managers, developers, sponsors, evaluaters, customers, and even visitors. What should such a presentation contain? The goal is to help the audience gain an appreciation of the problem, see the solution(s) chosen, understand why they were chosen, and gain confidence that the architecture is the right one for the job.
Here's an outline for a five-part, one-hour overview containing anywhere from 20 to 35 viewgraphs.
You may wish to have the following viewgraphs available to answer questions or to help discussion but not make them part of the standard presentation:
Preface the whole package with a title slide, sprinkle outline slides throughout to let the audience follow the outline of the presentation, and end with a "for further information" slide, and you're done.
If you're using an informal or ad hoc notation throughout your architecture, this overview presentation will be a good place to spot inconsistencies. Even something as minor as data flowing left to right in one diagram but right to left in another can be annoying and leave the audience puzzled.
A good presentation can help an architect in many ways. Put on videotape, it can free the architect from having to brief new hires or low-ranking visitors. It can be handed to junior designers as a way to groom them for technical leadership positions. And it helps establish a consistent vision of the architecture throughout an organization, which makes every architect's life easier.
Global analysis is the first design activity for each view in the Siemens approach to architecture design. As seen in Figure 10.4, this activity documents the rationale for the design decisions critical to the achievement of some requirement or goal.
Figure 10.4. Global Analysis begins by documenting the factors, such as requirements and goals, that influence the architecture design of a system. Analyzing factors results in a set of key issues and corresponding global strategies that guide the architecture design and improve its changeability with respect to the factors identified. Linking factors to issues to design decisions in this way provides traceability and documents the rationale for the architecture design.
The analysis must be global because key issues transcend boundaries between development activities, subsystems, and architecture viewtypes. Successful architects note the flexibility of the influencing factors and their likelihood of change, characterize how factors interact and their impact, and select cost-effective design strategies and project strategies to reduce the expected impact.
Factors include the constraints from the environment and the system requirements. Factors are documented in a factor table (see Table 10.1). A factor table describes the factor, characterizes its flexibility or changeability, and the impact that a change in the factor has on the system. For example, the organization places constraints on the system, such as requirements for time to market using available personnel and resources. These factors influence whether the system can be built. The requirements document the important features and quality attributes and may introduce constraints on technology. Factor tables record constraint-based rationale. Linking them to issue cards shows how they influence design decisions.
(Source: C. Hofmeister, R. L. Nord, and D. Soni, Applied Software Architecture (Addison-Wesley, 2000, p. 31).
After documenting the factors in factor tables, you begin organizing them around a small number of issues that drive the design of the architecture. These issues arise from the factors that have little flexibility, a high degree of changeability, and a global impact on the rest of the system. For example, analyzing the factors: (1) "time-to-market is short"; (2) "delivery of features is negotiable"; and (3) "new features are added continuously over the lifetime of the product" produces the architectural issue "Easy Addition of Features." Making it easy to add features will help meet the aggressive schedule by trading off function with time.
Issues are documented in an Issue Card (see Figure 10.5). The solution to an issue is in the form of strategies that guide the architect in making the design decisions. Such strategies may advocate the adoption of an architecture style or pattern, provide design guidelines (encapsulation, separation of concerns), place constraints on elements of the system, or introduce additional structure. The solution description records the analysis-based rationale that illustrates that the strategies satisfy the issue.
Figure 10.5. Sample Issue Card (C. Hofmeister, R. L. Nord, and D. Soni, Applied Software Architecture (Addison-Wesley, 2000, p. 33)). An issue card describes the issue, the influencing factors that affect this issue, and the solution to the issue.
How strategies are used is documented in a table linking them to design decisions. Solutions are revisited and may change as issues are resolved during design. There will be conflicts among the issues and the resulting trade-offs need to be made and documented.
Software Architectures and Documentation
Part I. Software Architecture Viewtypes and Styles
The Module Viewtype
Styles of the Module Viewtype
The Component-and-Connector Viewtype
Styles of the Component-and-Connector Viewtype
The Allocation Viewtype and Styles
Part II. Software Architecture Documentation in Practice
Documenting Software Interfaces
Choosing the Views
Building the Documentation Package
Other Views and Beyond
Rationale, Background, and Design Constraints