Software Architecture Documentation and Communication
This domain tests how to build an architecture description that is fit for its audiences: the required 42010 content, viewpoint selection, decision records, and keeping documentation alive.
Core rules and concepts
- A usable architecture description contains stakeholders and their concerns, viewpoints and views, correspondence rules, rationale and decisions, a glossary, and known constraints.
- Reuse established viewpoint libraries rather than inventing one per project: Kruchten's 4+1 (logical, process, development, physical, scenarios), the SEI Views and Beyond set (module, component-and-connector, allocation), or C4 (context, container, component, code) for accessibility.
- Architecture decision records capture context, decision, status and consequences. Supersede rather than rewrite, so the decision history survives.
- Correspondence rules make views checkable, for example every container must map to a deployment node and to a code repository module.
- Communication means one architecturally significant message per audience, supported by a walking skeleton where a diagram would be ambiguous.
Worked example
An external auditor needs a security viewpoint. Stakeholders are the auditor and the CISO; concerns are flows of personal data, trust boundaries and authentication. Model kinds are a data-flow diagram, a deployment diagram and a control table. The correspondence rule states that every trust boundary in the data-flow view maps to a named network zone in the deployment view, and that every zone has an owner in the control table. The rationale explains why TLS terminates at the edge rather than in each service. The reasoning: the viewpoint is reusable on later projects, and the correspondence rule turns two plausible-looking diagrams into a verifiable pair.
Traps that cost marks
- Producing many diagrams with no stated concern or audience.
- Recording a decision such as a messaging platform without the forces and alternatives behind it.
- Views that contradict each other because no correspondence check exists.
- Treating the architecture description as a one-off audit artefact that goes stale after the first release.