Architecture Documentation Choosing the Views
- Stakeholders and Their Documentation Needs
- Making the Choice
- Two Examples
- Summary Checklist
- Discussion Questions
This chapter is from the book
This chapter is from the book
This chapter is from the book
Poetry is a condensation of thought. You write in a few lines a very complicated thought. And when you do this, it becomes very beautiful poetry. It becomes powerful poetry. The equations [of physics that] we seek are the poetry of nature.
—Chen Ning Yang, 1957 Nobel Prize Winner for Physics, quoted in Bill Moyers: A World of Ideas, ed. Betty Sue Flowers, Doubleday, 1989, p. 313.
Before a view can be documented, it must be chosen by the architect. And that is the topic of this chapter: how an architect decides on the views to include in the documentation package.
In previous chapters, we explained how to represent all the various aspects of a software architecture. We discussed views that focus on coding aspects and on runtime aspects, and views that document the relationship of the software with its environment: module, C&C, and allocation viewtypes, respectively. Within a single development project, you will not document all the aspects of a software architecture. You will have to make decisions on what to document and to what level of detail. You also have to decide whether you want to define a new style to better support your project needs or to overlay two or more of the mentioned views.
But how many views are enough? How many are too many? And how complete does each view have to be? As a reader, you may be wondering whether we are going to impose an unrealistic documentation obligation on you, one that will produce beautiful exemplary documents that will never be used because the project will have run out of money at implementation time.
The reality is that all projects make cost/benefit trade-offs to pack all the work to be done into the time and the resources allocated for that work. Architecture documentation is no different. We have tried to explain the benefits of each kind of documentation and to make a compelling case for when you would want to produce it. If you can't afford to produce a particular part of the architecture documentation package, you need to understand what the long-term cost will be for the short-term savings.
Understanding which views to produce at what time and to what level of detail can be answered only in the concrete context of a project. You can determine which views are required, when to create them, and to what level of detail they have to be described in order to make the development project successful only if you know
What people you will have: which skills are available
What budget is on hand
What the schedule is
Who the important stakeholders are
This chapter is about helping you make those determinations. Once the entire documentation package has been assembled or at opportune milestones along the way, it should be reviewed for quality, suitability, and fitness for purpose by those who are going to use it.
9.1 Stakeholders and Their Documentation Needs
To choose the appropriate set of views, you must identify the stakeholders that depend on software architecture documentation. You must also understand each stakeholder's information needs.
The set of stakeholders will vary, depending on the organization and the project. The list of stakeholders in this section is suggestive but is not intended to be complete.
The documents mentioned for those stakeholders are ones in which they probably are interested, but the need for other documentation will vary from case to case. For instance, a project manager might not be interested in any C&C view. But a product with a Web-based client-server architecture might have a C&C view showing parts of the client-server architecture that are of interest to the project manager. So take the following lists as a starting point and adapt them according to the needs of your project.
A project manager cares about schedule, resource assignments, and perhaps contingency plans to release a subset of the system for business reasons. This person is not interested in the detailed design of any element or the exact interface specifications beyond knowing whether those tasks have been completed. But the manager is interested in the system's overall purpose and constraints; its interaction with other systems, which may suggest an organization-to-organization interface that the manager will have to establish; and the hardware environment, which the manager may have to procure.
The project manager might create or help create the work assignment view, in which case he or she will need a decomposition view to do it but will certainly be interested in monitoring it. As shown in Figure 9.1, a project manager, then, will likely be interested in
A top-level context diagram: module viewtype
A decomposition, uses, and/or layered view: module viewtype
A work assignment view: allocation viewtype
A deployment view: allocation viewtype
Overall purpose and constraints
)
Figure
9.1 A project manager usually creates the work assignments and therefore needs
some overview information of the software.
A member of the development team, for whom the architecture provides marching orders, is given constraints on how that person does his or her job. Sometimes, a developer is given responsibility for an element he or she did not implement, such as a commercial off-the-shelf product. Someone still has to be responsible for that element, to make sure that it performs as advertised and to tailor it as necessary. This person will want to know
The general idea behind the system. Although that information lies in the realm of requirements rather than architecture, a top-level context diagram can go a long way to provide the information.
Which element the developer has been assigned, that is, where functionality should be implemented.
The details of the assigned element.
The elements with which the assigned part interfaces and what those interfaces are.
The code assets the developer can make use of.
The constraints, such as quality attributes, legacy systems interfaces, and budget, that must be met.
As shown in Figure 9.2, a developer, then, is likely to want to see
A context diagram containing the module(s) he or she has been assigned: module viewtype
A decomposition, uses, and layered view: module viewtype
A view showing the component(s) the developer is working on and how they interact with other components at runtime: C&C viewtype
A mapping between views, showing the module(s) as components: module viewtype, C&C viewtype
The interface specification(s) of the developer's element(s) and the interface specifications of those elements with which they interact: module viewtype, C&C viewtype
The variability guide to implement required variability: module viewtype
An implementation view to find out where the assets he or she produces must go: allocation viewtype
A generalization view showing other modules that the developer can use to accomplish his or her work assignment: module viewtype
A deployment view: allocation viewtype
The documentation that applies beyond views, including a system overview
-
Rationale and constraints
)
Figure
9.2 Developers have interest mainly in the software itself, and therefore create
detailed module and C&C views and have some interest in allocation viewtypes.
Testers and integraters are stakeholders for whom the architecture specifies the correct black-box behavior of the pieces that must fit together. A unit tester of an element will want to see the same information as a developer of that element, with an emphasis on behavior specifications. A black-box tester will need to see the interface specification for the element. Integraters and system testers need to see collections of interfaces, behavior specifications, and a uses view so they can work with incremental subsets.
As shown in Figure 9.3, testers and integraters, then, are likely to want to see
A context diagram showing the module(s) to be tested or integrated: module viewtype
The interface specification(s) and behavior specification(s) of the module(s) and the interface specifications of those elements with which they interact: module viewtype, C&C viewtype
An implementation view to find out where the assets that build the module are: allocation viewtype
A deployment view: allocation viewtype
)
Figure
9.3 Testers and integraters need context and interface information, along with
information about where the software runs and how to build incremental parts.
Designers of other systems with which this one must interoperate are stakeholders. For these people, the architecture defines the set of operations provided and required, as well as the protocols for their operation. As shown in Figure 9.4, these stakeholders will likely want to see
A top-level context diagram: module viewtype and/or C&C viewtype
Interface specifications for those elements with which their system will interact: module viewtype, C&C viewtype
)
Figure
9.4 Designers of other systems are interested in interface specifications and
important system behavior.
Maintainers use architecture as a starting point for maintenance activities, revealing the areas a prospective change will affect. Maintainers will want to see the same information as developers, for they both must make their changes within the same constraints. But maintainers will also want to see a decomposition view that allows them to pinpoint the locations where a change will need to be carried out and perhaps a uses view to help build an impact analysis to fully scope out the effects of the change. Maintainers will also want to see design rationale that will give them the benefit of the architect's original thinking and save them time by letting them see already discarded design alternatives.
As shown in Figure 9.5, a maintainer, then, is likely to want to see
The views as mentioned for the developers of a system
A decomposition view: module viewtype
A layered view: module viewtype
Rationale and constraints
)
Figure
9.5 A maintainer has the same information needs as a developer but with a stronger
emphasis on design rationale and variability.
Application builders in a software product line tailor the core assets according to preplanned and built-in variability mechanisms, add whatever special-purpose code is necessary, and instantiate new members of the product line. Application builders will need to see the variability guides for the various elements, to facilitate tailoring. After that, application builders need to see largely the same information as integraters do.
As shown in Figure 9.6, a product line application builder, then, is likely to want to see
The views mentioned for an integrater
A variability guide: module and/or C&C viewtype
)
Figure
9.6 This person needs to understand what adaptations to make in order to build
new products.
Customers are the stakeholders who pay for the development of specially commissioned projects. Customers are interested in cost and progress and convincing arguments that the architecture and resulting system will meet the quality and functional requirements. Customers will also have to support the environment in which the system will run and will want to know that the system will interoperate with other systems in that environment.
As shown in Figure 9.7, the customer, then, is likely to want to see
A work assignment view, no doubt filtered to preserve the development organization's confidential information: allocation viewtype
A deployment view: allocation viewtype
Analysis results: module and/or C&C viewtype
A top-level context diagram in one or more C&C views: C&C viewtype
)
Figure
9.7 A customer is interested mainly in how the software works in the desired
environment.
End users do not need to see the architecture, which is, after all, largely invisible to them. But they often gain useful insights about the system, what it does, and how they can use it effectively by examining the architecture. If end users or their representatives review your architecture, you may be able to uncover design discrepancies that would otherwise have gone unnoticed until deployment.
To serve this purpose and as shown in Figure 9.8, an end user is likely to be interested in
A view emphasizing flow of control and transformation of data, to see how inputs are transformed into outputs: C&C viewtype
A deployment view to understand how functionality is allocated to the platforms with which the users interact: allocation viewtype
Analysis results that deal with properties of interest to them, such as performance or reliability: module and/or C&C viewtype
)
Figure
9.8 An end user needs to have an overview of the software, how it runs on the
platform, and how it interacts with other software.
Analysts are interested in the ability of the design to meet the system's quality objectives. The architecture serves as the fodder for architectural evaluation methods and must contain the information necessary to evaluate such quality attributes as security, performance, usability, availability, and modifiability. For performance engineers, for example, architecture provides the model that drives such analytical tools as rate-monotonic real-time schedulability analysis, simulations and simulation generators, theorem provers, and model-checkers. These tools require information about resource consumption, scheduling policies, dependencies, and so forth.
Recently, architecture evaluation and analysis methods have emerged as repeatable, robust, low-cost ways to make sure that an architecture will deliver the required quality attributes before the project commits to implementation based on it. The Architecture Trade-off Analysis Method (ATAM) exemplifies this new breed of methods. ATAM relies on suitable architecture documentation to do its work. Although ATAM does not prescribe specific documents that are required, it does offer general guidelines.
As shown in Figure 9.9, an ATAM practitioner is likely to be interested in
Views of the module viewtype family: module viewtype
A deployment view: allocation viewtype
A communicating-processes view: C&C viewtype
Applicable component-and-connector views: C&C viewtype
)
Figure
9.9 An analyst needs information from all viewtypes. Depending on the specific
analysis, other, more detailed information might be required.
In addition to generalized analysis, architectures can be evaluated for the following and other quality attributes, each of which suggests certain documentation obligations.
Performance: To analyze for performance, performance engineers build models that calculate how long things take. Plan to provide a communicating-processes view to support performance modeling. In addition, performance engineers are likely to want to see a deployment view, behavioral documentation, and those C&C views that help to track execution.
Accuracy: Accuracy of the computed result is a critical quality in many applications, including numerical computations, the simulation of complex physical processes, and many embedded systems in which outputs are produced that cause actions to take place in the real world. To analyze for accuracy, a C&C view showing flow and transformation of data is often useful because it shows the path that inputs take on their way to becoming outputs and help identify places where numerical computations can degrade accuracy.
Modifiability: To gauge the impact of an expected change, a uses view and a decomposition view are most helpful. Those views show dependencies and will help with impact analysis. But to reason about the runtime effects of a proposed change requires a C&C view as well, such as a _communicating-processes view, to make sure that the change does not introduce deadlock.
Security: A deployment view is used to see outside connections, as are context diagrams. A C&C view showing data flow is used to track where information goes and is exposed; a module decomposition view, to find where authentication and integrity concerns are handled. Denial of service is loss of performance, and so the secu rity analyst will want to see the same information as the performance analyst.
Availability: A C&C communicating-processes view will help analyze for deadlock, as well as synchronization and data consistency problems. In addition, C&C views in general show how redundancy, failover, and other availability mechanisms kick in as needed. A deployment view is used to show possible points of failure and backups. Reliability numbers for a module might be defined as a property in a module view, which is added to the mix.
Usability: A decomposition view will enable analysis of system state information presented to the user, help with determination of data reuse, assign responsibility for usability-related operations, such as cut-and-paste and undo, and other things. A C&C communicating-processes view will enable analysis of cancellation possibilities, failure recovery, and so on.
Infrastructure support personnel set up and maintain the infrastructure that supports the development and build of the system. You need to provide documentation about the parts that are accessible in the infrastructure. Those parts are usually elements shown in a decomposition and/or implementation view. Especially for configuration management, you have to provide a variability guide.
As shown in Figure 9.10, infrastructure support people likely want to see
A decomposition view: module viewtype
A uses view: module viewtype
An implementation view: allocation viewtype
A variability guide: module viewtype, C&C viewtype
A deployment view, allocation viewtype
)
Figure
9.10 Infrastructure support people need to understand the software artifacts
produced to provide tool support.
New stakeholders will want to see introductory, background, and broadly scoped information: top-level context diagrams, architectural constraints, overall rationale, and root-level view packets as shown in Figure 9.11. In general, anyone new to the system will want to see the same kind of information as his or her counterparts who are more familiar with the system but will want to see it in less detail.
)
Figure
9.11 New stakeholders need to have the same information as their counterparts.
Future architects are the most avid readers of architectural documentation, with a vested interest in everything. After the current architect has been promoted for producing the exemplary documentation, the replacement will want to know all the key design decisions and why they were made. As shown in Figure 9.12, future architects are interested in it all but will be especially keen to have access to comprehensive and candid rationale and design information.
)
Figure
9.12 A future architect has strong interest in all the architecture documentation.
Advice
Decide which stakeholders you need to provide architecture documentation for. Understand what type of information they need and at what level of detail. Use this information to decide what views are needed and how to structure them into view packages to easily support your stakeholders.
To summarize, the views you choose depend on the views you expect to use. For most nontrivial systems, you should expect to choose at least one view from each of the three viewtypes presented in this book: module, component-and-connector, and allocation. Beyond that, choose specific views based on anticipated uses by your stakeholders. The guidelines presented in this section are rules of thumb with which to begin. Remember that each view you select comes with a benefit but also a cost. You will undoubtedly wish to combine some views or to have one view serve in another's place; for instance, a work assignment view includes the information in a decomposition view, so you may not need both. Table 9.1 summarizes these guidelines.
)
Advice
Ask the Stakeholders
It is asking a lot of an architect to divine the specific needs of each stakeholder, and so it is a very good idea to make the effort to communicate with stakeholders, or people who can speak for those roles, and talk about how they will best be served by the documentation you are about to produce. Practitioners of architecture evaluation almost always report that one of the most rewarding side effects of an evaluation exercise comes from assembling an architecture's stakeholders around a table and watching them interact and build consensus among themselves. Architects seldom practice this team-building exercise among their stakeholders, but a savvy architect understands that success or failure of an architecture comes from knowing who the stakeholders are and how their interests can be served. The same holds true for architecture documentation.
Before the architecture documentation effort begins, plan to contact your stakeholders. This will, at the very least, compel you to name them. For a large project in which the documentation is a sizable line item in the budget, it may even be worthwhile to hold a half-day or full-day round table workshop. Invite at least one person to speak for each stakeholder role of importance in your project. Begin the workshop by having each stakeholder explain the kind of information he or she will need to carry out his or her assigned tasks. Have a scribe record each stakeholder's answer on a flip chart for all to see. Then present a documentation plan: the set of views you've chosen, the supporting documentation, and the cross-view information you plan to supplement them with. Finally, perform a cross-check to find requested but missing information and planned but unneeded documentation. Whether you hold a full-blown workshop or talk to your stakeholders informally, the result will be vastly increased buy-in for your documentation efforts and a clearer understanding on everyone's part of what the role of the architecture and its documentation will be.
Perspectives
Architecture Trade-off Analysis Method
Until recently, there were no reliable methods that would let us subject an architecture to a test to see whether it would deliver the required functionality and, at least as important, the required quality attributes of performance, modifiability, usability, security, availability, and so forth. The architect had to rely on his or her own past experience, styles and patterns in books, or, more likely, folklore. Only when code was developed, whether prototype or production, could the architecture be validated: Code testing served as architecture testing. But by then, changing the architecture was often prohibitively expensive.
Now, however, architecture evaluation methods have emerged that let us validate an architecture while it is still a paper design, before it has been hardened into code. As architecture evaluation matures to become a standard part of architecture-based development methods, architecture documentation takes on an additional use: serving as the fuel for an evaluation.
One of the most mature evaluation methods is the Architecture Trade-off Analysis Method (ATAM). Under ATAM, a four- or five-person evaluation team is gathered along with a set of stakeholders for the system whose architecture is being evaluated: designers, maintainers, end users, system administrators, and so forth. The analysis phase consists of nine steps.
DEFINITION
ATAM (Architecture Tradeoff Analysis Method) is an architecture evaluation method developed by the Software Engineering Institute.
Present the ATAM. The evaluation team leader describes the evaluation method to the participants, tries to set their expectations, and answers questions they may have.
Present business drivers. A project spokesperson, usually the project manager or the system customer, identifies the business goals that are motivating the development effort and hence what will be the primary architectural drivers, such as high availability, time to market, or high security.
Present the architecture. The architect describes the architecture, focusing on how it addresses the business drivers.
Identify architectural approaches. ATAM focuses on analyzing an architecture by understanding the architectural styles and approaches that it embodies. Approaches and styles, including those described in this and other books, have known characteristics in terms of how they promote or preclude certain quality attributes. In this step, the team compiles a list by asking the architect to explicitly name any identifiable approaches used but also captures any other approaches mentioned during the architecture presentation in the previous step.
Generate quality attribute utility tree. The quality factors that comprise system utility—performance, availability, security, modifiability, usability, and so on—are elicited. Then refinements are added. For example, security might be refined to disclose that data confidentiality and data integrity are important. Finally, the refinements are made operational by eliciting detailed scenarios that express the qualities. The utility tree serves to make concrete the quality attribute requirements, forcing the architect and customer representatives to define the relevant quality requirements precisely. Participants prioritize the utility tree scenarios according to how important each scenario is to the system and by how difficult the architect expects it will be to achieve.
Analyze architectural approaches. At this point, a prioritized set of concrete quality requirements from step 5 and a set of architectural approaches used in the architecture from step 4 exist. Step 6 sizes up how well suited they are to each other. Here, the evaluation team can probe for the architectural approaches that realize the important quality attributes. This is done with an eye to documenting these architectural decisions and identifying their risks, nonrisks, sensitivity points, and trade-offs. The evaluation team probes for sufficient information about each architectural approach to conduct a rudimentary analysis about the attribute for which the approach is relevant.
Brainstorm and prioritize scenarios. A larger set of scenarios is elicited from the group of stakeholders. Whereas the utility tree scenarios were generated using quality attributes as the context, here the evaluation team asks the stakeholders to contribute scenarios that speak to stakeholder roles. A maintainer will propose a scenario relevant to the architecture's ability to support maintenance, for example. These new scenarios are then prioritized by means of a facilitated voting process involving the entire stakeholder group.
Analyze architectural approaches. This step reiterates the activities of step 6, using the highly ranked scenarios from step 7. This analysis may uncover additional architectural approaches, risks, sensitivity points, and trade-off points, which are then documented.
Present results. Finally, the collected information from the ATAM needs to be summarized and presented back to the stakeholders. This presentation typically takes the form of a verbal report accompanied by slides but might also be accompanied by a more complete written report delivered subsequent to the ATAM. In this presentation, the evaluation leader recapitulates all the information collected in the steps of the method.
ATAM outputs are
The documentation of architectural approaches
The quality attribute utility tree, including the scenarios and their prioritization
The set of attribute-based analysis questions
The mapping from approaches to achievement of quality attributes
The risks and nonrisks discovered, and how the risks might undermine the architecture's business drivers
The sensitivity points and trade-off points found
A savvy architect can and should turn these outputs into part of the project's documentation legacy, which brings us full circle: The effort to prepare documentation to support an evaluation is paid back in full. Not only is the architecture validated or weaknesses discovered in time for repair, but also these outputs can be incorporated into the documentation as a part of the design rationale and analysis results.