P.2. Uses of Architecture Documentation

Architecture documentation must serve varied purposes. It should be sufficiently abstract to be quickly understood by new employees. It should be sufficiently detailed to serve as a blueprint for construction. It should have enough information to serve as a basis for analysis.

Architecture documentation is both prescriptive and descriptive. For some audiences, it prescribes what should be true, placing constraints on decisions to be made. For other audiences, it describes what is true, recounting decisions already made about a system's design.

The best architecture documentation for, say, performance analysis may well be different from the best architecture documentation we would wish to hand to an implementer. And both of these will be different from what we put in a new hire's "welcome aboard" package. The process of documentation planning and review needs to ensure support for all the relevant needs.

Understanding the uses of architecture documentation is essential, as the uses determine the important forms. Fundamentally, architecture documentation has three uses.

1. Architecture serves as a means of education. The educational use consists of introducing people to the system. The people may be new members of the team, external analysts, or even a new architect.
2. Architecture serves as a primary vehicle for communication among stakeholders. An architecture's precise use as a communication vehicle depends on which stakeholders are doing the communicating. Some examples are described in TableP.1.

DEFINITION

A stakeholder of an architecture is someone who has a vested interest in it.

Table P.1. Architecture documentation and stakeholder communication needs

Stakeholder	Communication
Architect and requirements engineers who represent the customer(s)	A forum for negotiating and making trade-offs among competing requirements
Architect and designers of the constituent parts	To resolve resource contention and to establish performance and other kinds of runtime resource consumption budgets
Implementers	To provide inviolable constraints and exploitable freedoms on downstream development activities
Testers and integraters	To specify the correct black-box behavior of the pieces that must fit together
Maintainers	A starting point for maintenance activities, revealing the areas a prospective change will affect
Designers of other systems with which this one must interoperate	To define the set of operations provided and required and the protocols for their operation
Managers	Basis for forming development teams corresponding to the work assignments identified, work breakdown structure, planning, allocation of project resources, and tracking of progress by the various teams
Product line managers	To determine whether a potential new member of a product family is in or out of scope and, if out, by how much
Quality assurance team	Basis for conformance checking, for assurance that implementations have in fact been faithful to the architectural prescriptions

Perhaps one of the most avid consumers of architecture documentation, however, is none other than the architect in the project's future. The future architect may be the same person or may be a replacement, but in either case is guaranteed to have an enormous stake in the documentation. New architects are interested in learning how their predecessors tackled the difficult issues of the system and why particular decisions were made. Even if the future architect is the same person, he or she will use the documentation as a repository of thought, a storehouse of detailed design decisions too numerous and hopelessly intertwined to ever be reproducible from memory alone.

QUOTATION

In our organization, a development group writes design documents to communicate with other developers, external test organizations, performance analysts, the technical writers of manuals and product helps, the separate installation package developers, the usability team, and the people who manage translation testing for internationalization. Each of these groups has specific questions in mind that are very different from the ones that other groups ask:

• What test cases will be needed to flush out functional errors?
• Where is this design likely to break down?
• Can the design be made easier to test?
• How will this design affect the response of the system to heavy loads?
• Are there aspects of this design that will affect its performance or ability to scale to many users?
• What information will users or administrators need to use this system, and can I imagine writing it from the information in this design?
• Does this design require users to answer configuration questions that they won't know how to answer?
• Does it create restrictions that users will find onerous?
• How much translatable text will this design require?
• Does the design account for the problems of dealing with double-byte character sets or bi-directional presentation?

  Kathryn Heninger Britton (Hoffman, Weiss 2001, pp. 337338)

1. Architecture serves as the basis for system analysis. To support analysis, the architecture documentation must contain the information necessary for the particular analyses being performed.
   • For performance engineers, architecture documentation provides the formal model that drives analytical tools, such as rate-monotonic real-time schedulability analysis, simulations and simulation generators, and even theorem provers and model-checking verifiers. These tools require information about resource consumption, scheduling policies, dependencies, and so forth.
   • For those interested in the ability of the design to meet the system's other quality objectives, the architecture documentation serves as the fodder for evaluation methods. The architecture documentation must contain the information necessary to evaluate a variety of attributes, such as security, performance, usability, availability, and modifiability. Analyses for each one of these attributes have their own information needs, and all this information must be in the architecture documentation.