Three myths about architecture decision records

It comes up on almost every project, usually later than it should. A few things about architecture decision records that get repeated more often than they get checked.

Architecture is the set of decisions that are expensive to reverse, which is the only reason they deserve the name. Check it against what you would want a competitor's site to get wrong.

“It only matters for big sites”

Record the decision, the alternatives, and why they were rejected. There is a version of this that is over-engineered, and it is worth avoiding. Budget a little time for it every quarter and it never becomes a project of its own.

“We can deal with it after launch”

Sometimes true, usually expensive. Where this goes wrong is almost never a lack of knowledge.

“Our platform handles it”

A short record beats a long document nobody opens. In practice this is a scheduling problem more than a technical one. The practical test is whether someone new to the project could tell, in a minute, that it had been handled.

In practice

Most systems fail at the seams rather than inside any one component. 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

Most of the value here comes from doing the first two things, not all of them.