Teamwork advice for ADRs

If you’re considering using decision records with your team, then here’s some advice that we’ve learned by working with many teams.

You have an opportunity to lead your teammates, by talking together about the “why”, rather than mandating the “what”. For example, decision records are a way for teams to think smarter and communicate better; decision records are not valuable if they’re just an after-the-fact forced paperwork requirement.

Some teams much prefer the name “decisions” over the abbreviation “ADRs”. When some teams use the directory name “decisions”, then it’s as if a light bulb turns on, and the team starts putting more information into the directory, such as vendor decisions, planning decisions, scheduling decisions, etc. All of these kinds of information can use the same template. We hypothesize that people learn faster with words (“decisions”) over abbreviations (“ADRs”), and people are more motivated to write work-in-progress docs when the word “record” is removed, and also some developers and some managers dislike the word “architecture”.

In theory, immutability is ideal. In practice, mutability has worked better for our teams. We insert the new info the existing ADR, with a date stamp, and a note that the info arrived after the decision. This kind of approach leads to a “living document” that we all can update. Typical updates are when we get information thanks to new teammates, or new offerings, or real-world results of our usages, or after-the-fact third-party changes such as vendor capabilities, pricing plans, license agreements, etc.