Documentation Conventions
Required Metadata
Section titled “Required Metadata”Every document must define:
titledescriptiondocumentTypestatusownerreviewDatelastVerifiedtags
The Starlight content collection validates those fields with Zod at build time.
Review Cadence
Section titled “Review Cadence”| Criticality | Review interval |
|---|---|
| Critical | 30 days |
| High | 60 days |
| Medium | 90 days |
| Low | 180 days |
The freshness script reads lastVerified and reports stale documents as JSON.
Diagrams
Section titled “Diagrams”Use Mermaid by default. Keep diagrams close to the explanation they support.
flowchart TD idea[Operational change] --> adr[ADR] adr --> runbook[Runbook] runbook --> checklist[Checklist] incident[Incident] --> postmortem[Postmortem] postmortem --> adrWriting Rules
Section titled “Writing Rules”- Prefer short, factual sections.
- Explain tradeoffs, not only commands.
- Every mutating operation must have a validation step.
- Every incident document must stay blameless.