Architecture decision records: the questions we get asked most

This is cheap to get right at the start and expensive to retrofit. The questions about architecture decision records that come up most often on our calls.

Most systems fail at the seams rather than inside any one component. If it only works because one person remembers to do something, it does not work yet.

Do we need to care about this?

Record the decision, the alternatives, and why they were rejected. It is worth being explicit about, because assumptions differ quietly. The teams that stay on top of it are the ones who put it on a calendar rather than a wish list.

Can it wait until after launch?

Occasionally. More often the post-launch version costs several times the pre-launch one. Small and consistent beats large and occasional here.

How do we know it is working?

A short record beats a long document nobody opens. There is a version of this that is over-engineered, and it is worth avoiding. The failure mode is not doing it wrong, it is doing it once and assuming it stays done.

The short version

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
• A short record beats a long document nobody opens — 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.