Architecture decision records, explained without the jargon

We end up explaining this on discovery calls often enough that it deserved writing down. Here is architecture decision records without the vocabulary that usually surrounds it.

Most systems fail at the seams rather than inside any one component. The version that survives contact with a real deadline is the simple one.

The short version

Record the decision, the alternatives, and why they were rejected. This is the sort of thing that compounds, quietly, in both directions. The version that survives contact with a real deadline is the simple one.

Why people complicate it

Most of the confusion comes from tooling rather than from the idea itself. None of that requires a large budget, only a decision and someone to own it.

The reasoning is what future teams actually need. That sounds obvious written down. It is still the thing most often skipped. Anything you cannot measure here, you are deciding by taste, which is fine as long as everyone knows it.

What to do next

A short record beats a long document nobody opens. The cost of getting this wrong is rarely visible on the day it happens. It is the sort of thing that looks like polish right up until it costs you an enquiry.

How to tell if yours is fine

The right architecture for a team of three is the wrong one for a team of thirty, and vice versa. Three things worth confirming about architecture decision records before you move on:

• Someone can say what the current setup is without going to look
• Record the decision, the alternatives, and why they were rejected — and you know whether that is true here
• There is a way to tell whether the last change to this helped

None of this needs a rewrite. Most of it is a morning's work once someone decides to do it.