Architecture Governance and Documentation
What this domain tests
This domain tests decision rights, standards and exceptions, and documentation that stays true after the project moves on.
Core rules
- Governance is about who decides, how conformance is checked, and how exceptions are granted - not about approval meetings. Define decision rights per domain and a waiver route with an expiry date.
- Architecture principles should be few, stated as rationale plus implications, and enforceable. "Use managed services by default" is a principle; "prefer microservices" is a slogan.
- Record decisions as ADRs: title, status, context, decision, alternatives considered, consequences (positive, negative, follow-ups). Superseded ADRs are kept, not deleted, so the reasoning trail survives.
- Tell the same story at different depths (C4: context, container, component, code) rather than mixing depths in one document. arc42 and ISO/IEC/IEEE 42010 supply structure when a template is needed.
- Documentation earns its place only if it reduces a real risk of misunderstanding; delete what nobody reads.
Worked example
A team wants to store sensitive data in a new region. The ADR records the driver (data residency law), options (single region with replication restrictions; dual region with key separation), the decision, consequences (higher cost, failover complexity, key management overhead), and a review trigger if the regulation changes. The exception to the "single cloud region" standard is logged with an owner and expiry, so the waiver does not outlive its reason.
Traps
- Writing ADRs retrospectively to justify a fait accompli, omitting rejected options.
- Governance as gatekeeping that slows delivery without reducing risk; fitness functions in the pipeline scale better than manual boards.
- Documents that duplicate and contradict each other because no one owns them.
- Forgetting operability documentation: runbooks, SLOs, and dependency maps are architecture too.