Nerd For Tech
Published in

Nerd For Tech

Architecture Decision Records (ADR) With Azure DevOps

Record your architectural and technical decisions for further reference, and have the new team members up to date from day one

Photo by Maarten Deckers on Unsplash

ADR is spoken of and documented well in other places, so I won’t spend much time talking about it. Just shortly, ADR is the process of storing the project’s architectural thinking and decisions for further reference. This further reference can be new members joining the team, existing members constantly fighting the patterns in the code, coming across similar problem later down the line etc. Team members should be convinced by the decision record as to why some alternatives were not entertained and why certain decision was made. Also, they should be aware that there is no right or wrong way actually — one problem can be solved in many ways, and the correct way to solve it is to follow the patterns in the current project you are working on. As the code is being much more read than written, when teammates read your code it will be familiar to them and easier to comprehend if it is written in a way similar to the other parts of the project.

ADR with Azure DevOps

Usually we recorded the technical decisions and patterns in a wiki document. As new members were joining the team they asked questions about stuff, so we didn’t want to repeat ourselves and documented some of the decisions. After some time, I came across ADR and I thought: wow, this actually had a name. Obviously I didn’t think we were the only ones with the problem, I was just surprised. So I put some more thought to it. Since every decision is then translated to user stories or tasks, I figured out that it can be placed in the backlog, in the same fashion we collect and document the requirements for the sprints. Azure DevOps lets you choose whether the user story or feature is business or technical — so we mark these features as technical. In the feature itself we explain the decision and alternatives, and the user stories and tasks are the actual technical execution of the decision.

Let’s imagine a project that we already manage with Azure DevOps. We’d already have the backlog organized, possibly having epics which would contain features, and the last, most granular level would be the user stories.

How a project that has campaigns, organizers and participants could be shown

Let’s now come up with an architectural decision, and see how we can record it. Say we need a monitoring tool. More specifically, a tool to monitor production exceptions.

A simple example architecture decision record

It is very important when recording the architecture decision, to also list the other alternatives that were considered, and why the decision went against them. This is actually more important than recording the decision itself, as if you come back to this document in the future, and if the conditions are same, the same decision will probably still stand.

Another important point is to set up the context. In the example, we disregarded the other options not because they are bad, more difficult to set up or wouldn’t work in our scenario, but because we already had an existing subscription and good past experience. If this changes in future, we will consider the monitoring tool again.

Finally, the documenting tool should support revision history out of the box, so you would know who took and who changed the decision, status etc.

You can place the architecture decision records in a separate epic

Export as always up to date documentation

One very cool side effect of recording your architecture decisions in Azure DevOps is the possibility to export them.
You can use Enhanced Export, which can print out any query as a PDF document. Then, whenever necessary, you can export the ADRs and hand them out.
We actually use this to provide new teammates with the project documentation and the decision records at the same time, so the new members will be up to date from day one. Obviously, a prerequisite of this is to keep the epics, features and user stories up to date.

Part of the exported document, which contains all epics and features




NFT is an Educational Media House. Our mission is to bring the invaluable knowledge and experiences of experts from all over the world to the novice. To know more about us, visit

Recommended from Medium

Create a Game App with HMS

This is a test

1/2 Dependency Injection is everywhere

Making Camera Shake using Impulse Listener Extensions

Performing Some Task On AWS Cloud Using CLI(Command Line Interface).

How to Maintain UPM Package Part 3

HackTheBox : FriendZone

Basics of Kotlin


Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store
Boris Donev

Boris Donev

As a technical team lead of several startup projects, I've come across different issues which I'll try to document and maybe help someone else.

More from Medium

Azure AD B2C setup for API Management Developer portal

DB migrate from on-premise to Azure MySQL(1)

Securing your Azure Functions App with API Management

What is Azure API Management? Why Should We Use It? What are the benefits? (Part 1)