Writing architecture decisions that outlive the programme
Most architecture documentation is written for the steering committee and read by nobody after sign-off. Decision records written for the engineer who inherits the system in three years are a different artefact, and they change how programmes behave.
The difference between a programme that lands and one that does not is usually architectural discipline: the willingness to make trade-offs explicit, write them down, and review them with the people who will live with the consequences. This is a practical note on how we do that, and on the mistakes that turn decision records into shelfware.
A decision record is not a design document
Design documents describe what the system is. A decision record describes a fork in the road: the options that were live, the constraints that made one of them win, and what would have to change for the decision to be revisited. It is short, it is dated, and it is never edited after acceptance; a superseding decision gets its own record.
The audience is the engineer who inherits the system, not the committee that approved it. That changes the writing. Jargon gives way to the actual constraint: the reason the queue is not the managed one is that the sovereign region did not offer it in 2026, and that is worth knowing in 2029 when it does.
Decide at the right altitude
Programmes fail at both extremes: a record for every library choice that nobody reads, or a single monolithic architecture document that hides the real forks. The test we use is reversibility. If reversing the choice would take more than a sprint, or would touch more than one team, it gets a record. A framework version bump does not. Choosing an event backbone does.
Keep the count honest. A mature programme carries a few dozen live decisions, not hundreds.
Write the constraint, not the preference
A weak record says the team preferred PostgreSQL. A strong record says the workload has strong consistency requirements across three aggregates, the on-premise estate only offers two supported databases, and the team's operational experience is with one of them. Constraints can be checked later; preferences cannot.
Include the option that lost and why. Future teams will be tempted by it again, often with a vendor in the room.
Review with the people who will live with it
The review is where the value is. We run decision reviews with the client's platform team, the security function, and the people who will be on call, not only the architects. The on-call engineer asks the question the architect skipped: what happens at three in the morning when this fails.
Decisions made in a room without operations end up owned by nobody. Decisions reviewed with operations get runbooks.
Governance that does not slow delivery
Records live in the repository next to the code, are proposed through the same pull-request flow, and are accepted in a weekly thirty-minute forum with a quorum. Anything that needs longer than that is not ready to be decided. Steering committees see a summary; they do not gate engineering decisions.
Over a multi-year programme, the decision log becomes the most-read document in the estate. It is how new teams learn why the system is shaped the way it is, and it is how the client keeps control when suppliers change.
Where we apply this in practice
Working on this in your own organisation?
If any of this maps to a programme you are running, we would be glad to compare notes.