Documentation Beyond Views

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:

1. How the documentation is laid out and organized so that a stakeholder of the architecture can find the information he or she needs efficiently and reliably. This part consists of a documentation roadmap and a view template.
2. What the architecture is. Here, the information that remains to be captured beyond the views themselves is a short system overview to ground any reader as to the purpose of the system, the way the views are related to one another, a list of elements and where they appear, and a glossary and an acronym list for the entire architecture.
3. Why the architecture is the way it is: the background for the system, external constraints that have been imposed to shape the architecture in certain ways, and the rationale for large-scale decisions.

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.

Documentation Roadmap

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:

1. Description of the parts. The roadmap begins with a brief description of each part of the documentation package. Each entry may contain document information, such as the author, location, and latest version. The major part of the roadmap describes the views that the architect has included in the package. For each view, the roadmap gives
   1. The name of the view and what style it instantiates.
   2. A description of the view's element types, relation types, and property types. These descriptions can be found in the style guide from which the view was built and can be included in the roadmap directly or by reference. They let a reader begin to understand the kind of information that he or she can expect to see presented in the view.
   3. A description of what the view is for. Again, this information can be found in the corresponding style guide. The goal is to tell a stakeholder whether the view is likely to contain information of interest. The information can be presented by listing the stakeholders who are likely to find the view of interest, and by listing a series of questions that can be answered by examining the view.[1]

      [1] 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.

      ADVICE

      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.

   4. A description of language, modeling techniques, or analytical methods used in constructing the view.[2]

      [2] 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

   

2. How stakeholders might use the package. The roadmap follows with a section describing how various stakeholders might access the package to help address their concerns. This might include short scenarios, such as "A maintainer wishes to know the units of software that are likely to be changed by a proposed modification."

View Template

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

System Overview

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.

ADVICE

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

• List the element or elements of the second view that correspond to it.
• Indicate whether the correspondence is partial or complete.
• If the element of the first view has an interface, list any interface or module in the second view that corresponds to it.

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:

• Ensure at least one mapping between a module view and a component-and-connector view.
• If your system uses more than one module view, map them to each other.
• If your system uses more than one component-and-connector view, map them to each other.

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.

Directory

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.

To reuse the design, we must also record the decisions, alternatives, and trade-offs that led to it.

(Gamma+ 95, p. 6)

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.

To understand all is to forgive all.

Evelyn Waugh, Brideshead Revisited (Little, Brown, 1945, © 1973)

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.

ADVICE

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:

• The design team spent significant time evaluating options before making a decision.
• The decision is critical to the achievement of a requirement/goal.
• The decision seems to not make sense at first blush but becomes clear when more background is considered.
• On several occasions, you've been asked, "Why did you do that?"
• The issue is confusing to new team members.
• The decision has a widespread effect that will be difficult to undo.
• You think it's cheaper to capture it now than not capturing it will be later.

Once you've decided to document a design decision, try to describe it with the following five-part outline:

1. Decision: a succinct summary of the design decision.
2. Constraints: the key constraints that ruled out other possibilities. The system's requirements constitute a large body of constraints but by no means all. Sometimes, a particular operating system must be used; other times, a particular middleware system; at other times, the components derived from legacy systems. Perhaps there were funding pressures, or a particular commercial component was chosen because of the organization's relationship with its vendor. Perhaps key stakeholders wielded influence that affected the design. Business goals, such as time to market, often influence an architecture, as do quality attribute goals, such as modifiability, that are not always documented in a system's requirements. Some design choices result from constraints generated by other design decisions and from trade-offs with other solutions.
3. Alternatives: the options you considered and the reasons for ruling them out. The reasons need not be technical: A future architect will especially appreciate your insights about what dead ends to avoid, as well as your candor if you think you made the wrong decision or if you could just as well have adopted another approach.
4. Effects: the implications or ramifications of the decision. For example, what constraints does the decision impose on downstream developers, users, maintainers, testers, or builders of other interacting systems?
5. Evidence: any confirmation that the decision was a good one. For example, you can explain how the design choice meets the requirements or satisfies constraints. There are various frameworks for reasoning about quality attributes, such as rate-monotonic analysis and queuing models. Use cases and quality scenarios are also used to evaluate the architecture with respect to the requirements.

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.

ADVICE

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.

1. Problem statement: 23 slides. State the problem the system is trying to solve. List driving architectural requirements, the measurable quantities you associate with them, and any existing standards/models/approaches for meeting them. State any technical constraints, such as a prescribed operating system, hardware, or middleware.
2. Architectural strategy: 2 slides. Describe the major architectural challenges. Describe the architectural approaches, styles, patterns, or mechanisms used, including what quality attributes they address and a description of how the approaches address those attributes.
3. System context: 12 slides. Include one or two top-level context diagrams that clearly show the system boundaries and other systems with which yours must interact.
4. Architectural views: 1218 slides. Use the views you've chosen as the backbone of the presentation. For each view, include the primary presentation from at least the top-level view packet and, depending on the amount of detail you want to include, perhaps a few second-level view packets. Naturally, each should include a notation key.

   An overview presentation is the one case for which a cartoon does not have to be accompanied by the supporting documentation, but you will want to have it available for answering questions.

   For each viewgraph showing a primary presentation, make a couple of accompanying viewgraphs that explain (a) how the architecture shown supports the functionality and achieves the system qualities that reside with that view and (b) the rationale for choosing that design. You may wish to annotate or color some of the cartoons to show programmatic information about the elements, such as which elements are provided by COTS products or other source, the state of an element's development, the amount of risk posed by an element, or the scheduled delivery or other milestone of an element. You need not include every view in the presentation, but you should include at least one view from each of the modules, C&C, and allocation viewtypes.

   Where views can be straightforwardly mapped to each other, include viewgraphs that do so. This will be very useful in conveying the overall picture.

5. How the architecture works: 310 slides. Trace up to three of the most important use cases. If possible, include the runtime resources consumed for each use case. You should be able to extract the traces from your behavioral documentation in the form of, for example, sequence diagrams or statecharts.

   Show the architecture's capacity for growth with a trace of up to three of the most important change scenarios. If possible, describe the change impactestimated size/difficulty of the changein terms of the changed elements, connectors, or interfaces.

   Depending on the importance of each item, consider tracing a scenario that illustrates any of the following: concurrency, failure recovery, error propagation, or key end-to-end data flows. Again, you should be able to extract this information from your behavioral documentation.

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:

• The set of stakeholders for the documentation and a sketch of the information needs of each (23 slides)
• Glossary (12 slides)

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.

PERSPECTIVES

Global Analysis

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.

R.N.