Standard : Documentation is accurate, accessible, and maintained alongside the code it describes
Purpose and Strategic Importance
Documentation is a first-class engineering concern, not a finishing touch. When documentation lives alongside the code it describes, is reviewed in pull requests, and is written for the next engineer rather than the current one, it becomes a force multiplier for the whole team. Architecture decision records capture the reasoning behind technical choices. READMEs enable fast onboarding. API docs reduce integration friction. Runbooks empower anyone on-call to respond with confidence. Together, these artefacts represent the institutional knowledge that allows teams to operate and evolve their systems sustainably.
Documentation that drifts from the systems it describes is worse than no documentation — it misleads and wastes time. This standard establishes that accuracy and accessibility are ongoing engineering responsibilities, not one-time tasks. Teams that embed documentation into their definition of done, review it as seriously as code, and invest in structured approaches like Architecture Decision Records (ADRs) and operational runbooks, build systems that are more resilient, more transferable, and far easier to maintain over time.
Strategic Impact
- Engineers can onboard, navigate, and contribute to unfamiliar systems significantly faster when documentation is accurate, co-located with code, and written with future readers in mind.
- Architectural decisions are preserved with their original context and rationale, preventing teams from unknowingly re-litigating solved problems or repeating past mistakes.
- Operational runbooks enable confident incident response from any team member on rotation, reducing the bus factor and the dependency on a small number of individuals who hold critical knowledge.
- Accurate API documentation reduces integration friction for consuming teams, cutting the number of questions, misunderstandings, and costly integration bugs that arise from unclear contracts.
Risks of Not Having This Standard
- Tribal knowledge accumulates in a small number of individuals, creating dangerous single points of failure when engineers leave, move teams, or are unavailable during incidents.
- Onboarding new engineers takes significantly longer, reduces early productivity, and creates a poor first impression that contributes to attrition and dissatisfaction.
- Teams repeatedly revisit architectural decisions without access to the original context and reasoning, leading to inconsistency, wasted effort, and avoidable rework.
- Outdated runbooks and operational guides lead to slower, more error-prone incident response, with on-call engineers forced to improvise in high-pressure situations.
- Undocumented APIs and integration points create hidden dependencies, making changes more risky and increasing the likelihood of breaking downstream consumers without warning.
CMMI Maturity Model
Level 1 – Initial
| Category |
Description |
| People & Culture |
Documentation is seen as a low-priority afterthought and is rarely written, updated, or read by the team. |
| Process & Governance |
There are no expectations around documentation as part of delivery and no standards exist for format or location. |
| Technology & Tools |
Documentation exists in scattered locations such as emails, chat messages, and personal notes with no single source of truth. |
| Measurement & Metrics |
No measures exist for documentation quality, coverage, or accuracy and no feedback mechanisms are in place. |
Level 2 – Managed
| Category |
Description |
| People & Culture |
Some engineers document their work informally, typically in wikis or READMEs, but practices vary widely across the team. |
| Process & Governance |
Basic documentation expectations exist for major components but are not consistently applied or reviewed. |
| Technology & Tools |
A central wiki or documentation platform is in use but content is often outdated and ownership is unclear. |
| Measurement & Metrics |
Documentation completeness is assessed informally during handovers or incidents rather than as a routine check. |
Level 3 – Defined
| Category |
Description |
| People & Culture |
Teams treat documentation as part of the definition of done and documentation is reviewed alongside code in pull requests. |
| Process & Governance |
Standards define when and how to write READMEs, ADRs, API docs, and runbooks, and these are applied consistently. |
| Technology & Tools |
Documentation lives in version control alongside code, enabling review, history, and synchronised updates with changes. |
| Measurement & Metrics |
Teams track documentation coverage for key artefacts and review documentation health as part of regular team rituals. |
Level 4 – Quantitatively Managed
| Category |
Description |
| People & Culture |
Engineers proactively identify and address documentation gaps, raising them as work items with the same urgency as technical debt. |
| Process & Governance |
Documentation quality is assessed through structured reviews, onboarding feedback, and post-incident analysis of runbook effectiveness. |
| Technology & Tools |
Tooling enforces documentation requirements in CI pipelines, flagging missing or stale documentation before changes are merged. |
| Measurement & Metrics |
Time-to-productivity for new engineers, runbook usage during incidents, and documentation freshness are tracked as leading indicators. |
Level 5 – Optimising
| Category |
Description |
| People & Culture |
Documentation excellence is a recognised engineering value and engineers mentor others in writing clearly for future readers. |
| Process & Governance |
Documentation standards are continuously improved based on onboarding experience, incident feedback, and evolving system complexity. |
| Technology & Tools |
Automated tooling surfaces stale documentation, suggests updates based on code changes, and tracks coverage across the repository. |
| Measurement & Metrics |
Documentation quality is linked to measurable outcomes including reduced onboarding time, faster incident resolution, and fewer integration bugs. |
Key Measures
- Percentage of services and components with up-to-date READMEs covering purpose, setup, dependencies, and operational guidance
- Number of Architecture Decision Records (ADRs) created per quarter as a proportion of significant technical decisions made
- Time-to-first-contribution for new engineers as a proxy measure of onboarding documentation quality and accessibility
- Runbook coverage across all production services measured as the proportion with documented incident response procedures
- Proportion of pull requests that include documentation updates when behaviour, APIs, or operational characteristics change
- Feedback scores from new team members rating the quality and usefulness of documentation during their onboarding experience