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.
- 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.
- 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. |
| 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.
- 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.
Категории