Uses of Software Architecture Documentation
Practice ¡ Chapter 12
Why bother documenting?
Section titled âWhy bother documenting?âMany projects skip architecture documentation, treat it as an afterthought, or only produce it because a process or contract demands it. Good architects instead treat documentation as a first-class deliverable because it pays back across the whole project life cycle. An architecture only has value if it can be communicated to the people who must build, use, and change the system.
The six core uses
Section titled âThe six core usesâ| Use | What it buys you |
|---|---|
| Communicate the architecture | Conveys the systemâs structures and their interactions to technical and non-technical audiences alike. |
| Assist the development team | Shows interfaces, elements, and constraints so developers know what to build, what to reuse, and which decisions are already fixed. |
| Educate team members | Onboards new joiners and helps existing developers understand the design decisions behind what they are working on. |
| Provide input for reviews | Supplies the detail reviewers need to evaluate an architecture against requirements and quality attribute scenarios, and to compare alternatives. |
| Reuse architectural knowledge | Preserves decisions, rationale, and lessons learned so they can be leveraged on other systems. |
| Help the architect | Answers the flood of stakeholder questions and serves as external memory. |
Communicating to different stakeholders
Section titled âCommunicating to different stakeholdersâ- Different stakeholders (developers, management, other stakeholders) care about the architecture for different reasons and priorities.
- An architecture is abstract enough that many audiences can reason about the system from it.
- Different architecture views target different audiences â no single artifact serves everyone. See Creating Architecture Descriptions (ADs).
Assisting and constraining developers
Section titled âAssisting and constraining developersâ- Documentation communicates design decisions, preventing developers from making the wrong implementation choices.
- Architecture deliberately restricts design freedom and constrains implementation â reducing overall system complexity.
- Seeing available interfaces tells developers what to implement versus what is ready to consume.
Keep it current
Section titled âKeep it currentâ- When the architecture changes, the documentation must change with it; stale docs mislead the team.
Feeding reviews and enabling reuse
Section titled âFeeding reviews and enabling reuseâ- Review teams use documentation to check whether functional requirements and quality attribute scenarios can be met, and to compare candidate architectures.
- Reuse is especially valuable across a software product line, where products share functional/non-functional requirements and look-and-feel; parts of one productâs architecture can serve others.
Helping the architect specifically
Section titled âHelping the architect specificallyâ- Acts as external memory for complex systems revisited months or years later.
- Supports pitching a project, securing funding, and giving presentations.
- Preserves answers if the architect leaves the project or organization.
Citations
Section titled âCitationsâ- Software Architectâs Handbook (Packt, 2018), Ch.12 âUses of software architecture documentationâ, pp. 907-913.