Where Architecture Documentation Ends

Early in this book, we examined the question of where architecture ends and nonarchitectural design begins. A related question is where architecture documentation ends and other documentation issues begin. Architects and architectures of all stripes exist. Data architectures, security architectures, enterprise architectures, reference architectures, installation architectures: The list is endless.

Some of the terms are clearly in scope. Reference architectures, for instance, appeared in our discussion of documenting variability, as the essence of a reference architecture is its ability to be tailored to the needs of any of a family of systems. Security architectures, although not addressed as such, are covered by making sure that a security specialist can find information of analytical use in one or more of the "normal" styles.

But some writers undoubtedly incorporate as architecture some aspects of system documentation that are outside the scope of this book. We completely agree with Boehm et al. (Boehm et al., p. 527) that architecture is not an island and should be related to other important system development documents; however, all the organizations, templates, and guidelines in this book were created to capture software and system architectures, which consist of the structure or structures of the system, which consist of software elements, the externally visible properties of those elements, and the relationships among them.

How does the guidance in this book relate to architectures that occupy outlying regions of the topic area? To the extent that these "architectures" depend on architectural structures as captured by styles and views, the principles in this book hold. But writing down system installation procedures, for example, is not architectural. Nevertheless, the principles for sound documentation extend well beyond the realm of "mainline" architectures. Involvement of stakeholders, letting the uses of documentation guide its contents, controlling repetition, using a standard organization, avoiding ambiguity: These and other principles form the foundation of a high-quality documentation task.

Many other topics in software engineering are related to documenting software architecture. Chief among them is the general topic of software architecture. Other topics that you want to be aware of but that are outside the scope of this book are architecture description languages, commercial components, hypertext documentation, and configuration management. In the remainder of this section, we give a glimpse at these topic areas and provide pointers for further study.

11.9.1 Architecture Description Languages

A large body of work is associated with the formal representation of software and system architectures. A number of researchers in industry and academia have proposed formal notations for representing and analyzing architectural designs. Generically referred to as architecture description languages (ADLs) or even architecture definition languages, these notations usually provide both a conceptual framework and a concrete syntax for characterizing software architectures. They also typically provide tools for parsing, unparsing, displaying, compiling, analyzing, or simulating architectural descriptions written in their associated languages.

While all these languages are concerned with architectural design, each provides certain distinctive capabilities. Examples of ADLs include

• Acme (Garlan, Monroe, and Wile 2000) supports the definition of new architectural styles.
• Adage (Coglianese and Szymanski 1993) supports the description of architectural frameworks for avionics navigation and guidance.
• Aesop (Garlan, Allen, and Ockerbloom 1994) supports the use of architectural styles.
• Darwin (Magee et al. 1995) supports the analysis of distributed message-passing systems.
• MetaH (Vestal 1998) provides guidance for designers of real-time avionics control software.
• Rapide (Luckham et al. 1995) allows architectural designs to be simulated, and has tools for analyzing the results of those simulations.
• SADL (Moriconi, Qian, and Riemenschneider 1995) provides a formal basis for architectural refinement.
• UniCon (Shaw et al. 1995) has a high-level compiler for ar-chitectural designs that support a mixture of heterogeneous component and connector types.
• Wright (Allen and Garlan 1997) supports the formal specification and analysis of interactions among architectural components.

No ADL provides the facilities to completely document a software architecture, where "complete" is defined in the context of this book's prescriptions. But many ADLs provide excellent means for discharging part of the architect's documentation obligation. Chapter 8, for instance, covered formal notations for specifying behavior, and several ADLs could be brought to bear in that regard. An ADL that provides a good means to express rich structure could be used to help render the views' primary presentations, with the added bonus that analysis based on that ADL's capability would then be automatically placed on the fast track.

Besides their analytical powers, ADLs have the advantage of enforcing their formal models, making it more difficult to specify architectures that are internally inconsistent or ambiguous. Like all languages, however, this constraint can be helpful or painful, depending on how consistent that formal model is with your needs at the time.

11.9.2 Commercial Components

In recent years, software development using preexisting or purchased components has become commonplace. This trend has far-reaching effects, one of which is that systems are being composed of large-grained components over which the developer wields little control. The primary source of preexisting components is the commercial marketplace, and market dynamics add new dimensions of design complexity and risk to software development. These new dimensions create special documentation obligations that you should be aware of. Software projects composed of custom-built software components are dominated by optimization decisions in which the components are tweaked to meet the needs of the developer, whereas those composed primarily from preexisting software components are dominated by selection decisions, in which the developer's needs are tweaked to meet the available supply of components. Although software architecting is traditionally associated with top-down, custom design, nothing about documenting software architectures or our prescriptions about it precludes meeting the needs of either type of design method. As we prescribe throughout the book, documenting the rationale behind decisions is one of the most important aspects of architectural documentation.

Selection Decisions

Selection decisions arise when there is a bounded set of a priori design options. In this situation, the fundamental design problem is to select the option that best satisfies specific design qualities. When building from preexisting software components, you are not free to define the scope of components, their interfaces, and their interaction mechanisms, as these decisions have already been made by the component developer. This greatly restricted design freedom results in your need to focus on selection rather than on optimization. Component selection decisions are often strongly interdependent, with one selection decision constraining others. These interdependencies are, in themselves, a principal source of selection criteria and result in complex decision-making activity. You must document the criteria for component selection and any interdependencies among the criteria. Working with preexisting components requires a new way of designing; an additional set of problems is introduced into the decision-making process when the preexisting components come from commercial vendors.

COTS-Related Selection Criteria

Today, and for the foreseeable future, the commercial marketplace is the primary source of software components; you cannot ignore the effects of commerce when using COTS (commercial-off-the-shelf) components. In particular, you must consider three qualities of commercial software components.

1. Commercial software components are complex. Vendors package complexity to attract a market. However, components can become so complex that even experts do not know all their features. In practice, there are bound to be gaps in knowledge about component features and behavior, which poses a significant source of risk.
2. Commercial software components are idiosyncratic. Although components may implement standard features, it is innovation that attracts customers. Innovation results in knowledge that is component specific. However, it also results in integration difficulties owing to mismatches among innovativeand therefore nonstandardcomponent features.
3. Commercial software components are unstable. New features must be introduced to generate sales and to preserve product differentiation. Therefore, knowledge about components is not just vendor specific but also has a short lifespan. Moreover, design assumptions based on component features can be fragile and subject to untimely revision.

Documentation for systems built from commercial components must include information that helps mitigate the risk associated with these three characteristics. As a guide, we suggest that you follow the prescription given by Wallnau, Hissam, and Seacord [2002], in which they introduce component ensemble as a fundamental design abstraction and provide a notation for capturing design decisions as the selection activity progresses.

Key aspects of their prescription include annotating component interactions with constraints; design elements, with credentials or postulates. Credentials describe what is known about an element and how it came to be known; postulates describe what one should discover and how it might be discovered. What a designer chooses to credential or postulate is left open, but suggestions might include the version of the component, the credibility of the component supplier, other known risks associated with using the component, or some quality-related properties that must be measured before the component is selected. Additional constructs are provided to help record the progress of the decision-making activity in terms of which designs are feasible, which might be, which are not, and why.

We won't try to summarize the book here other than to say that working with commercial components requires a new way of thinking about design decisions; there's a whole book on the subject, and it is highly recommended if you are playing that game.

11.9.3 Hypertext Documentation

By now, you must have asked yourself at least once and maybe a hundred times, "How am I supposed to navigate through all these documents?" Fortunately, Web-based documentation is becoming the norm. Hyperlinking your documents can provide instant access to related documents, definitions, catalogues, and external references. Hyperlinking also relieves you of all the problems associated with keeping multiple copies of documents around: You make one copy and link to it wherever the information contained in it is needed. (Recall the second rule of sound documentation: Avoid unnecessary repetition.)

We have not dedicated a chapter to Web-based documentation, because we assume that you can easily find the places where hyperlinking will be the most use to you and other users of the documentation you create. However, don't underestimate the challenge of creating useful hypertext documentation. Usability and other issues are active areas of research. For more information on creating hypertext documentation, visit the Web site of the ACM special-interest group on hypertext, hypermedia, and the Web (ACM).

11.9.4 Configuration Management

And last, but not least, what book on documentation would be complete without stressing once againrecall the sixth rule of sound documentation, "Keep documentation current but not too current"the importance of keeping your documentation complete and consistent? Nothing is worse than opening up a bunch of architecture documents and trying to figure out which of them represents the most recent version of the system. Documents should be dated and versioned. If someone is looking at several figures, it should be obvious at a glance which figures are from the same version of the system. You probably think of software configuration management systems more in terms of keeping track of the code associated with your project, but we recommend that you think of the documentation that you are creating as software too and treat it just as carefully as you do the code that is produced based on it.