↓Skip to main content

Decision Records

·3 mins

As you go and progress in your life, you take decisions. These decisions have a context which explains why you took them. Time passes, this context starts to vanish and your memory has a hard time restituting it in the way it was.

This is a problem that is common within teams: you take a decision and 12 months later, your team is reevaluating that decision after having lost the context that led it to it. Conflicts might arise because that decision is not understood anymore or opinions have changed about it. Challenging decisions is a good thing though a team needs to be aligned to take the proper one.

This is where having Decision Records comes handy. They can have different name and take many forms but the gist of it is to log multiple things about a decision:

  • a title: presents the decision in a succint way
  • its context: what led to take this decision, what were the alternatives, why were they discarded…
  • the actual decision: out of the context, what we decided
  • its consequences: what is the impact of this decision, positive or negative
  • its status: a decision can be accepted/deprecated or superseded

These records should be simple to read and understand. I’ve been using Decision Records in multiple contexts and some teams use git and markdown while others are using Confluence to track them. I personnally prefer git and markdown as you can add an approval process on your merge requests and every modification is logged as a commit. I generally use a repository organized in approximately the same way the Rust RFCs are. We have a template that serves as the source for every record. When someone wants to propose a decision, they either create an issue to discuss the topic first or, if they are already confident the proposal is mature enough, they can create a record out of the template and create a Merge Request to the repository. Once done, the team will review the Merge Request and will merge the decision or not depending on the outcome. It is generally advised to create an issue to discuss the topic first as we can already hash out a lot of questions and stir the decision in the right direction for the team. Each decision takes the ID of the merge request and becomes records/XXXX-decision-short-title.md where XXXX is the merge request ID.

These are generally called Architectural Decision Records but you can apply them onto anything, these could be decisions on the organization of your team which would then be the source to the process in place.

I can’t stress enough how valuable these documents are, I often go back to the records to make sure I understand why we took a decision at some point in time. Also, when onboarding someone, it makes it easy for that person to review past decisions and understand the history that led to what the team is. These documents should be easy to write but they provide a great value.

You will probably have a hard time at first deciding whether anything should be written in a record. Over time, the team will understand what it finds valuable or not. My advice woule be: if it impacts the team, log it; if you have a doubt, log it.

To conclude, Thoughtworks has the Lightweight Architectural Decision Records adopted in its Tech Radar (last updated in 2018) where you can find a more detailed description of what Decision Records are. If you are not using them already, I encourage you to give it a go!

– This is day 12/100 of #100DaysToOffLoad!

↑