During a recent project to set up research-ready computers in the cloud using Codespaces, we found ourselves making lots of decisions in the Research Experience team.
We wanted to record those decisions as we made them, so we experimented with an approach known as Architectural Decision Records, or ADRs.
ADRs record what’s happened and why
An ADR is a short document where we write down the details of any significant decisions we make as a team. Usually, ADRs are stored alongside the code they document - you can see ours in a folder, in the same repository as our source code.
Our ADRs include:
- a date, so we know when we made the decision
- a status, so we know whether or not the information still applies, or has been superseded by a later ADR
- a “context” section, describing the ‘forces at play’ and laying out any relevant facts; this section often includes a list of any other options we’ve considered
- a “decision” section, our response to those forces and a short description of the decision we took
- a “consequences” section, where we describe the positive, negative and neutral consequences of the decision
We use a simple template for each new ADR.
Michael Nygard has written in more detail about the structure of an ADR. We also liked some of the advice written up by Andrew Harmel-Law in his article about architecture at martinfowler.com.
Writing notes for our future selves
We’ve discovered that we quite like writing ADRs, for a few reasons:
- Writing ADRs encourages us to reflect on decisions, and helps to ensure that everyone on the team understands each decision
- We’re not taking decisions in isolation, but with the support of the rest of the team
- We create a record that we can look back on in future, and that we can share with new team members as they join, to give them some useful background
- Documenting today’s decisions makes tomorrow’s decisions a little bit easier; we’ll have a record of why we did what we did, and how we ended up where we are
- We want to work in the open, and our ADRs are another way we can do that
Learning how to do ADRs better
Generally, we found that ADRs were quick to write once we got into the habit of writing them. Occasionally, we would find them more difficult. At that point, it was helpful to stop and consider why. Often, it was because we were trying to document several decisions rather than a single decision, so it made more sense to break them into several shorter updates. As a rule of thumb, if the ADR is more than a page long, it’s worth taking a step back and considering whether it’s covering more than one decision.
We found it best to write an ADR as soon as possible after making the decision. We made this mistake a few times, and tried writing them after the fact, near the end of a piece of work. That was much more difficult, because we had to tease apart several decisions and try to remember the context of each one.
It’s also a good idea to keep the ADRs in the same place as the code, so that they’re easy to find and easy to update.
We think that ADRs aren’t just useful for developers. You may find that recording decisions on research projects helps you and other researchers in future. For example, decisions like why you choose to use DataTables rather than DataFrames in your R code; or why one piece of data was included but not another. If you’ve been using them on your research projects, please get in touch, we’d love to hear about it.
More ADRs please
Although we’ve dabbled a bit with ADRs before, this was the first time that a Bennett Institute team really took them to heart.
You only start to see the benefits of ADRs when there are lots of them. After all, you never quite know what decisions you’ll be revisiting in future, and any new person joining the team will want to see a full picture rather than a partial one.
So, we think we’re going to be making more use of ADRs in our team, and we’re going to be encouraging other teams to use them too.