documentation-discipline

To decide between an ADR and a runbook, use a decision tree that evaluates whether the context requires recording a design choice or an operational procedure. The tree guides artifact selection to ensure documentation is useful and discoverable.

An architecture decision record (ADR) is a document capturing a design choice and its context. You should write an ADR when a cross-team coordination or architectural decision needs to be recorded, standardized, and made durable for stakeholders.

Structure a runbook using a template with required expected results and explicit rollback procedures. This standardizes operational outputs and ensures verification steps are included during incidents.

The best way to prevent documentation rot is applying governance rules that enforce immutability, assign specific ownership, define storage locations, and establish regular review cadences for your decision logs and runbooks.

You should leave knowledge in chat when a decision tree evaluation determines the information does not warrant a durable artifact. This avoids an unsustainable docs burden while ensuring significant tribal knowledge is still captured.

Yes, you can use this approach for onboarding and incident response. It provides artifact selection guidance and templates to produce stakeholder-facing summaries, runbooks, and operational scaffolds during cross-team coordination.