Standard : Systems are documented in a way that reflects how they evolve
Purpose and Strategic Importance
This standard ensures that system documentation evolves alongside the system itself, reflecting both design intent and real-world implementation. By maintaining accurate, up-to-date, and accessible documentation, teams can onboard faster, make safer changes, and retain architectural integrity over time.
Aligned to our "Architect for Change" policy, this standard closes knowledge gaps, strengthens accountability, and reduces delivery friction. Without it, organisations risk confusion, inconsistency, and repeated mistakes due to missing or misleading documentation.
Strategic Impact
- Faster onboarding and safer decision-making
- Greater cross-team consistency and knowledge flow
- Reduced delivery risk and rework from misunderstood systems
- Stronger engineering culture grounded in transparency and trust
Risks of Not Having This Standard
- Slower time to value and increased technical rework
- Loss of critical system knowledge when people leave
- Friction during scaling, integration, or incident response
- Reduced confidence in system understanding or ownership
CMMI Maturity Model
Level 1 – Initial
| Category |
Description |
| People & Culture |
Documentation is rarely maintained and often tribal. |
| Process & Governance |
Docs are written once at project start and quickly become outdated. |
| Technology & Tools |
No shared tooling for storing or updating documentation. |
| Measurement & Metrics |
No visibility of documentation coverage or usage. |
Level 2 – Managed
| Category |
Description |
| People & Culture |
Some teams maintain documentation but updates are sporadic. |
| Process & Governance |
Intentional architecture is documented more often than reality. |
| Technology & Tools |
Wiki or document storage exists but lacks version control or workflows. |
| Measurement & Metrics |
Informal feedback identifies gaps or outdated content. |
Level 3 – Defined
| Category |
Description |
| People & Culture |
Teams embed documentation into their workflows and treat it as part of the product. |
| Process & Governance |
Standards exist for maintaining living documentation aligned to system changes. |
| Technology & Tools |
Docs are integrated with repos or tooling that reflect system state. |
| Measurement & Metrics |
Documentation freshness and completeness are reviewed periodically. |
Level 4 – Quantitatively Managed
| Category |
Description |
| People & Culture |
Documentation is a shared responsibility reinforced by coaching and reviews. |
| Process & Governance |
Change reviews require documentation updates to be in scope. |
| Technology & Tools |
Tooling links architectural artefacts to code and config changes. |
| Measurement & Metrics |
Coverage, update frequency, and usage analytics are actively tracked. |
Level 5 – Optimising
| Category |
Description |
| People & Culture |
Documentation continuously improves through peer review and automation. |
| Process & Governance |
Learnings from incidents and projects drive updates across systems. |
| Technology & Tools |
Intelligent systems suggest updates based on observed changes. |
| Measurement & Metrics |
Documentation impact is measured through onboarding speed and delivery performance. |
Key Measures
- Percentage of systems with up-to-date, peer-reviewed documentation
- Developer satisfaction with ease of understanding system design and history
- Time to onboard new engineers or teams
- Frequency of documentation updates relative to system changes
- Measurable reduction in rework caused by misunderstanding or misalignment