Documentation Standards

Architecture documentation is a communication artifact, not a compliance checkbox — its value is proportional to how often it is consulted and trusted to be current. The C4 Model (Simon Brown) provides four zoom levels (Context, Container, Component, Code) that serve different audiences without requiring a single "big bang" diagram. OpenAPI / Swagger specifications are the standard for REST API documentation, enabling SDK generation, mock servers, and contract testing. Decision logs (ADRs) record the context and reasoning behind architectural choices, preventing institutional memory loss as team composition changes. Runbooks operationalize documentation into executable procedures for on-call engineers.

Key Points

• C4 Model: Level 1 (Context) = system in relation to users and external systems; Level 2 (Container) = deployable units (web app, API, DB); Level 3 (Component) = modules within a container; Level 4 (Code) = classes/functions — typically auto-generated from IDEs
• ADR format: Title + Date + Status (Proposed/Accepted/Superseded) + Context (forces at play) + Decision (what we decided) + Consequences (positive and negative outcomes) + Alternatives Considered; stored in /docs/adr/ in the repository
• OpenAPI 3.x specification: defines endpoints, request/response schemas, authentication, error codes; enables Swagger UI for interactive docs, Prism for mock servers, and Pact for consumer-driven contract testing
• Runbook structure: title, severity it addresses, trigger (alert that fires this runbook), triage steps (copy-paste commands), decision tree, escalation path, and links to relevant dashboards and related runbooks
• Documentation-as-code: store all docs (ADRs, runbooks, architecture diagrams as code using Mermaid/PlantUML) in Git alongside the code they describe; review in PRs; deprecate with the system they document
• Onboarding documentation: "day one" guide that gets a new engineer to a running local environment and first PR within 4 hours; the time-to-first-commit metric directly measures documentation quality
• Documentation decay: assign doc owners; add "last verified" dates; embed documentation review into architecture review and quarterly planning processes; stale docs are worse than no docs (mislead engineers in production)
• Diátaxis framework (Daniele Procida): categorizes docs into Tutorials (learning-oriented), How-To Guides (problem-oriented), Reference (information-oriented), and Explanation (understanding-oriented) — prevents the common mistake of writing everything as reference when tutorials are needed