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.
A stakeholder of an architecture is someone who has a vested interest in it.
|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.
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:
Software Architectures and Documentation
Part I. Software Architecture Viewtypes and Styles
The Module Viewtype
Styles of the Module Viewtype
The Component-and-Connector Viewtype
Styles of the Component-and-Connector Viewtype
The Allocation Viewtype and Styles
Part II. Software Architecture Documentation in Practice
Documenting Software Interfaces
Choosing the Views
Building the Documentation Package
Other Views and Beyond
Rationale, Background, and Design Constraints