How to write an ADR to document a decision?

The tribe wisdom didn't work. Usually, the whole idea falls apart when a new team member hears, "X knew everything about it. They don't work here anymore." How can we fix the problem by writing ADRs?

A website with the header "Documentation" and links to several documents
Photo by Sigmund on Unsplash

Writing Architecture Decision Records (ADRs) became popular, which is good because the other popular approach was to ignore documentation and rely on "tribe wisdom."

The tribe wisdom didn't work. Usually, the whole idea falls apart when a new team member hears, "X knew everything about it. They don't work here anymore."

Thankfully, we started writing some documentation. But is it useful? What can we do to produce the best possible ADRs?

Why do we write ADRs?

We want to document a decision. That's pretty obvious. But what aspects of the decision do we want to document? What is important?

Do we care who made the decision? Sometimes. If you are unlucky to work at an organization where the decisions are not honored unless the Big Name has signed them off.

Do we care what the system's state was before the decision was made? Most likely. Especially if the implementation is not a one-week effort. During the implementation, we will be in some weird state between the old and the new. It would be good to have some idea about the old implementation.

How to document the decision criteria?

The people reading the ADR one year later will want to know why you made the decision you have made. They may have a different opinion. They have seen the consequences of your decision. They want to see what you were thinking. So please, please tell them why you made the decision. What did you consider? What was important to you?

Also, remember to write down what you choose to ignore and why. Write down everything obvious. In one year from now, those things won't be obvious anymore.

Documenting the solutions you considered

Hopefully, you have a few options you have to consider. I say hopefully because if you have only one option, there is no decision to make. Why do you even write the ADR in this case?

You may want to write down that it was the only available option. Good. Do it. If there is only one option, there will be dozens in two years, and the one you choose today will be the worst. It's good to point out you had no other choice.

If you have more options, please write down what you considered. You already wrote down the criteria. Now, you should evaluate all the options using those criteria.

Documenting the decision

What do we need to know about the decision you made? As said before, we need the criteria, and we need the options you considered. What else?

We need the problem. Why are you even making the decision? What do you want to achieve?

How will you know you have achieved the goal? That's the hard part. How often do we say we want to improve a measurable metric and don't even dare to measure it afterward? If you don't measure it anymore, nobody will tell you didn't achieve the goal. We don't know. Perhaps, we have succeeded. Let's celebrate. No. Stop it. That's ridiculous. How will you know you achieved the goal?

Documenting the foreseen consequences

Did you think measuring whether you achieved the goal was the hard part? This one is going to be worse.

There are no silver bullets. The decision you make will have consequences. Some of them will be negative. Can you see them? Please tell us what you foresee and why you think you can live with those problems.

If you don't see problems, you are delusional or trying to invent a problem to justify the solution you want to implement. Sorry. It is the truth, and you needed to see it.

The ADR template

Here is the structure you may follow to write a useful ADR. Of course, it doesn't mean your ADR will be useless if you don't. However, it is hard to make a mistake if you follow this template:

  • What is the problem you are trying to solve?
  • How will you know that you achieved the goal?
  • How will you make the decision? What are the criteria?
  • What are your options?
  • Do they fulfill the requirements? How?
  • What decision have you made?
  • What future problems do you see? What will you do about them, or why can you ignore them?