Documenting Architecture Choices with Architecture Decision Record

Have you wondered why an project uses Dapper instead of Entity Framework? Did a new person asked you why you chose X and not Y when during onboarding into the project? Someone asked you and you didn’t remember because it was a long time ago? That’s an unfortunate situation.

We, developers, don’t really like creating the documentation. That’s because we have a certain image of documentation, which consists a lot of pages. Often it’s hosted far away from the code, in a wiki, for example. It gets outdated and is not a part of source control. It’s rarely structured… Therefore, we don’t like writing it.

Documenting can be better. I really enjoy writing architecture decision records with a certain template and keeping it close to my code.

Architecture Decision Records To The Rescue

There are other ways, than a outside of the project wiki, to document things that happen around the project. The one I really like is the Architecture Decision Log, which contains Architecture Decision Records (ADR’s) that can help you keep track of the decisions that have been made. And why. The “why” is important. Maybe a decision that was right back some time, is no longer valid. Because of the fact that the decision was written down, we may easily reference the previous document and explain why there’s a new way of doing something. Therefore, we have the change log of our decisions, just like we do with the code.

Architecture Decision Record Template

In the picture, you can see an popular template of Architecture Decision Record, by Michael Nygard. It’s divided into 4 paragraphs. Status, context, decision, and consequences.

Architecture Decision Record template
Architecture Decision Record Template that I use


The status describes whether the decision is proposed, rejected, accepted, deprecated, etc.


The context describes what is the motivation for decision or change.


The decision describes what we’re proposing or doing.


The consequences describe what are the implications of the decision that has been made.

I mostly like this structure, because it challenges you to think about the consequences of the decision that is made. Writing the decision with it’s consequences down and persisting it (look at next paragraph) has a certain benefit. You’ll be able to go back to the way that you thought about the problem. You can then easier understand, remind yourself or finally change the decision.

For example, if you know that the Event Sourcing might benefit your project and business. But you’re omitting it, because you know that the development team doesn’t have any experience with that technique. Besides that, the deadline is tight. This decision has the consequences. We’ll be able to deliver the project faster, but we’ll not be able to benefit from event sourcing’s capabilities.

Keep the Architecture Decision Records Up To Date And Make Them Easily Accessible

I think that documentation should be easy to access. It should be easy to maintain. It should also be persistent and belong to the source control system. I like to keep the docs close to the code. In the same repository. Then, when I do research, or I have to make a decision I can easily create a markdown document and describe why I’ve decided to go with a certain approach.

I like to write it down as an Architecture Decision Record. Then I don’t have to worry about memorizing it. When onboarding a new person he/she asks why we chose X or Y, no problem. I can either tell him/her where to find the decision or refresh my memory and then talk about it. And it doesn’t take a lot of time! I don’t really worry about making it ultra detailed. I just follow the template of ADR.

Oh, and keeping the Architecture Decision Log close to the code allows other people working on the code to enrich the records easily.

Are you documenting your architecture choices? Why not?

Let's stay in touch!