Architecture Decision Records (ADRs) are a wonderful tool. They force you to think through the options before you make a decision. They also provide institutional memory that’s independent of people, which is great for new joiners with their inevitable Why? questions.

Michael Nygard’s template shows what sections an ADRs should have. There are several other templates out there as well.

Nygard’s template has a Status section, which only contains the status of the ADR. At most teams in Adevinta, we add the names of the people involved in making the decision to the Status section, something like Accepted by ray.sinnema on 2023-09-04. Most of the templates I’ve seen don’t have this, although some do, e.g. Joel Parker Henderson, and Planguage.

Recently, I got challenged on this practice. They argued that individuals don’t matter, since the team as a whole makes the decisions. I love such challenges, since they force me to think through and articulate my reasons better. So let’s look at why adding names to ADRs adds value.

Personal branding

Like it or not, it’s important for your name to pop up if you want a promotion. Now, inside your team people will know your strengths. But not all promotions are decided inside a team, i.e. by your manager.

The more you climb the ranks, the more important it becomes for people outside your team to see the value that you add.

Having your name in ADRs, especially the more impactful ones, helps with your personal brand. You can point to those ADRs as proof that you can make difficult decisions well and are ready for the next step in your career.

External stakeholders

Sometimes a decision can’t be made by the team alone. The decision may have budget impact, for instance, and need approval from a budget owner or from the Procurement department.

Or the decision may affect how you store personal data and the Privacy department needs to give their blessing.

Having the names of those outside collaborators in the ADR shows that you’ve consulted the right people and may prevent challenges to the decision from outside the team (CYA).

Contact person

Most companies have more than one team. It may be interesting for other teams to look at your team’s decisions.

For instance, you may have an ADR on a public cloud migration and the other team is about to embark on a similar migration. They could learn from your research into the options and their pros and cons.

Having your name in the ADR gives the other team a person to contact. If it’s not there, they need to contact the team’s manager and ask them for a person to reach out to. That may sound like a small step, but every extra roadblock means you could hamper the transfer of knowledge.

Writing an ADR isn’t a daily activity. Many teams may go long periods of time without needing to write one. This means the opportunities for team members to learn how to make good decisions and write them up in ADRs are relatively scarce. Looking at other team’s ADRs may help, especially if you can have a follow-up conversation with the decision makers.

Counterargument

Some might argue that you can see the ADR contributors from the Git history (you are versioning your ADRs, aren’t you?). However, that’s not universally true, because

• Not everyone who contributes ideas to an ADR will create a commit or PR comment. This is especially true when you mob-write your ADRs.
• Some people may not have access to Git, like PMs, or VPs.
• If you make your ADRs available via some other system, like Backstage, it may not be clear to the reader where the ADR is stored.

Conclusion

I think there are good reasons for adding the names of the deciders to ADRs, especially in larger organizations. Whether this is in the Status section, or in some other section doesn’t matter much.

Acknowledgments

Thanks to Francesco for raising this topic, to Alexey for helping me crystallize my thoughts, and to Gabe for reminding me to write about the counterargument.