What Gets Documented
In one line: Document structural changes, not tactical ones — the trigger is "alters how the system works," not "changes how it behaves."
Not everything warrants the same documentation treatment. The table maps content categories to audience, format, and update triggers.
| Category | Audience | Content Type | Update Trigger |
|---|---|---|---|
| Architecture | Developers, AI agents | Data flow diagrams, component maps, service inventories | New service, new integration, structural refactoring |
| ADRs | Decision-makers, future developers | Context, decision, consequences, alternatives | Technology choice, pattern change, data model decision |
| API Reference | Integrators, frontend developers | Endpoint documentation, request/response schemas, auth requirements | New endpoint, schema change, behavior change |
| Strategy & Business | Partners, investors, regulators | Business context, market analysis, regulatory positioning | Funding rounds, partnership changes, regulatory developments |
| Compliance | Regulators, auditors, legal | Regulatory mapping, data-processing records, audit methodology | New AI feature, new data processing activity, regulatory update |
| Features | Prospects, demo audiences | Feature showcases, capability descriptions, competitive positioning | New feature launch, significant enhancement |
| Project state | Fresh AI agents, returning developers | STATE.md — current milestone, last shipped, blockers, next-up | Per-shipped-artifact (task lands, ADR accepted, milestone closes); see Section 11.6 |
The table is deliberately conservative. Not every code change triggers a documentation update. Configuration changes, bug fixes, and minor refactoring do not need documentation. The triggers are structural changes that alter how the system works, not tactical changes that fix how it behaves.