Architecture documentation: ISO 42010, views, C4, UML, SysML, and arc42
ISO/IEC/IEEE 42010:2022 distinguishes architecture from its architecture description. Documentation should answer stakeholder concerns through viewpoints and models. One giant diagram mixes scopes and becomes ambiguous.
Core ideas and patterns
| Idea | What it solves | Cost, limit, or warning |
|---|---|---|
| Stakeholder/concern | Explains who needs which architectural answer | Missing stakeholders create missing views |
| Viewpoint/view | Defines conventions for a concern and its resulting representation | A view without a question becomes decoration |
| Model kind | Defines how a model is constructed and interpreted | Notation must have explicit semantics |
| C4 context/container/component/code | Provides hierarchical static structure zoom | C4 does not replace behavior, data, or threat views |
| C4 dynamic/deployment | Shows runtime interaction or physical mapping | Keep scenario and environment explicit |
| UML | Models structure and behavior with standardized diagrams | Over-detailed class diagrams age quickly |
| SysML | Models multidisciplinary system requirements, behavior, structure, and parametrics | Needs trained audience and model governance |
| arc42 | Organizes architecture documentation into practical sections | Template completion is not architectural quality |
| ADL/model as code | Makes architecture queryable, diffable, and automatable | Generated diagrams still need clear purpose and layout |
How to apply it
For each stakeholder concern choose the smallest useful view: context, container, component, domain, sequence, state, data flow, deployment, threat, or operations. Title the scope, declare notation, label relationships and protocols, include legend, owner, date, and link to decisions. Store near source where possible.
Evidence, not opinion
Run diagram review: scope and abstraction are clear; every element has name/type/responsibility; every relationship is directional and labeled; technologies and boundaries are explicit; diagrams match deployment. Automate drift checks where the architecture model can be compared with code or infrastructure.
Small example
The context view answers executives and external integrators. A container view answers developers. A deployment view answers operations. A threat/data-flow view answers security. They share element names but do not force every detail into one picture.
Feynman check
Explain the design to a new engineer without using the pattern names. State the problem, the forces that conflict, the chosen boundary or mechanism, what can fail, and the evidence that would prove the choice still works.