Architecture without ceremony: decisions designed to age well
Good architecture documents aren't PowerPoint battles. They're short, dated, and they give the reader two years from now a fair chance.
In every other project I walk into, I find the same stack: a twelve-page architecture document from kickoff, half of it already obsolete, that nobody reads anymore. Next to it, a wiki with diagrams that still mention components long since deleted. And then the actual truth, lurking in Slack threads, pull-request comments, and the head of the one engineer who’s been there five years.
It doesn’t have to be this way. But it requires a different posture toward architecture documentation.
Architecture isn’t a plan — it’s a history of decisions
The most important shift: architecture documentation isn’t about describing how the system looks. It’s about recording which decisions we made, when, and why. The current state of the system already lives in the code — that’s also where it’s most accurate.
What isn’t in the code is the why. Why this message broker instead of a database? Why this authentication flow instead of OIDC out of the box? Why three services instead of one?
Every new hire asks these questions by their second week. Without documented answers, the team slips into a collective amnesia where every decision gets re-argued every few years — usually with a different outcome and always with friction.
ADRs: short, dated, honest
My tool of choice is the Architecture Decision Record. One short Markdown file per decision, in the repository, with three required parts:
- Context: What was the situation when we decided?
- Decision: What did we actually choose?
- Consequences: What does this choice cost us, and what do we get for it?
Optional but very helpful in practice:
- Alternatives: What did we rule out, and why?
- Status: proposed, accepted, superseded — with dates.
That’s it. An ADR is rarely longer than one screenful.
Why this ages well
The real value: when someone asks two years from now why this service looks the way it does, they find the ADR. They see the state of the world at the time — different data volumes, different compliance requirements, different team size. They can decide on solid ground whether the old call still holds, or whether it’s time for a successor ADR.
By comparison, a classical architecture document ages on its first page: “In May 2024 we chose…” — and by June half of it is already wrong.
A practical entry point
If you want to start: write one ADR this week — about the next decision your team is going to make. Not about all the old ones. Work forward, not backward. Three months in, you’ll have a small collection of living history — and a documentation format that doesn’t become a burden.
If you’d like a sparring partner for introducing ADRs or for a larger architecture inventory, drop me a line.