Software Architect · Module 18
Architecture documentation isn't for the archive. It exists so new people can understand the system, and old people can remember why decisions were made.
ADR · C4 · runbook · decision record · context
You document more than the outcome — you document the context: why this option, which alternatives were rejected, and when to revisit the decision.
An ADR fixes a decision in time
A photo of the construction site doesn't replace the blueprint, but it does help you understand why the wall ended up here.
An Architecture Decision Record typically holds context, decision, consequences, alternatives, and status. It doesn't have to be long. Its job is to preserve the reasoning.
A year later, the team may not remember why they picked Postgres, why they passed on Kafka, or why they kept a sync API. The ADR keeps you from re-running the same argument without the original context.
A diagram has to answer a question
The subway map doesn't show the sewers — passengers don't need them. A good diagram picks its level of detail.
The C4 model is useful as a set of levels: context, container, component, code. A stakeholder needs the context. The team needs containers and the important components. Incident response needs the runtime view and the dependencies.
One giant diagram of "the whole system" is usually useless: it either goes stale or becomes unreadable.
Good documentation lives next to the changes and has an owner.
Example: an ADR for the queue choice
In meeting minutes, the decision matters — but so does why the other options didn't fit.
The ADR records: we need to deliver domain events with replay, ordering by key, and durable storage. We considered RabbitMQ, managed Kafka, and a database outbox. We chose managed Kafka for the throughput — and accepted the operational cost and the schema governance burden.
A document like that helps a future team see when the decision still holds and when the context has shifted.
Anti-example: Confluence as a graveyard
A warehouse of old instructions looks impressive — until you realise no one knows which one is current.
The documentation lives apart from the code, has no owner, doesn't get updated on PRs, and is full of three-year-old screenshots. New hires quickly learn to ignore it.
Fewer documents with a clear lifecycle work better: owner, last-reviewed date, link from code, required updates on architectural change.
- Which decisions deserve an ADR? - Which diagram does a new hire need on day one? - Which runbooks does on-call need? - How does the team learn that a document is stale?