Documentation Standards¶
Status: 🟢 Active | Owner: Engineering Enablement | Last Reviewed: 2025-Q4
Introduction¶
Documentation is an engineering discipline. Undocumented code, missing runbooks, and absent ADRs are not neutral — they accumulate cost. Each missing runbook extends incident resolution time. Each missing ADR causes the same architectural decision to be relitigated. Each stale README wastes onboarding time for every engineer who joins the team.
These standards define the minimum documentation requirements for every service and shared component in the organisation. They are verified at the production readiness gate and in the quarterly shared asset health check.
Documentation Ownership¶
Documentation ownership follows service and component ownership. The team that owns a service owns its documentation. When ownership transfers, documentation quality is a prerequisite: the incoming team must be able to operate the service using only its documentation, without asking the outgoing team.
| Document Type | Owner | Audience | Staleness Signal |
|---|---|---|---|
| README | Squad | New team members, contributors | Local setup steps fail |
| Runbook | Squad | On-call engineers | Alert fires but procedure is wrong or missing |
| API documentation (OpenAPI) | Squad | API consumers | Client integration fails; consumer files bug |
| ADRs | Tech Lead | Future engineers, architecture reviewers | Engineers re-debate settled decisions |
| Architecture diagrams | Squad / Architect | Reviewers, new engineers | Diagram shows components that no longer exist |
Documentation as a Merge Gate¶
The following documentation gaps block PR merge or production deployment:
| Gap | Gate |
|---|---|
| OpenAPI spec not updated for API change | CI — openapi-diff diff check |
| No runbook for a new alert | Production readiness review |
| README has no local setup instructions | Production readiness review |
| ADR missing for a significant architecture decision | Architecture review / code review |
TODO without a ticket reference | CI — commitlint rule |
What You Will Find Here¶
| Page | Intent |
|---|---|
| Architecture Decision Records (ADRs) | When ADRs are required, the standard template, lifecycle states, and a worked example |
| README Standards | Required sections, the freshness obligation, and a full template |
| API Documentation | OpenAPI 3.1 requirements, required fields, publishing standards |
| Runbooks & Operational Guides | Runbook template, location standards, coverage requirements |
| Diagrams as Code | Mermaid and C4-PlantUML standards, diagram location conventions |
Last reviewed: 2025-Q4 | Owner: Engineering Enablement