Architecture Decision Records (ADRs) have been a part of my everyday workflow for over a year now and along the way I've learned that the most important thing about writing ADRs, especially when working with different teammates who have vastly different writing styles (or lack thereof), is writing them well.

If you are new to ADRs or are convinced they are painful to write, then I have a few tips which will hopefully save you from a lot of potential pain. On the other hand, if you are curious about why you should be writing ADRs in the first place, I've outlined several reasons in a previous article.

All of the suggestions you'll see come from first-hand experience, so pay special attention to even the most "simple". If these tips are already abundantly clear and you feel as though your time is being wasted, then count yourself as one of the lucky ones whose team members are authors beyond reproach and exude world-class communication of a technical kind.

Tips

Check Your Grammar

Without a doubt, this suggestion will come off as the most obvious and least valued, but it is also the most impactful. Not only is bad English hard to understand but it's hard to interpret, especially when it comes to nuanced explanation. Grammar mistakes in the thick of an idea distacts and wastes the time of any reviewer. Your teammates will not thank you for having to guess your intentions and incessantly ask questions to refine your position (and you will likely become agitated as well).

Luckily, the solutions are nearly effortless: always re-read your ADR before asking others to review it and always put ADRs through a spellchecker. Reminders to read your ADR and spellchecking can both be easily automated or made part of a review process checklist, so save yourself time by doing so.

Explain Why You’re Not Using Alternatives

This one is huge. Justifying why certain alternatives were not used in the face of the ADRs final decision not only helps you, the author, better understand your own ideas, it also does two critical things:

1. It captures the context of the problem. One of the killer features of ADRs is the ability to capture historical context for why a decision was made. Explaining your position is doing just that.
2. It saves everyone time by helping reviewers avoid questions like "Why didn't you use x or y?" or "Have you considered Z?" when you actually did consider x, y, and Z, but you just didn't say you did.

Another thing worth noting is that in the discussion of alternatives, it is always important to list the cons of choosing your down decision against another. Every decision is a tradeoff, so every decision should include both pros and cons.

Be Brief

Some concepts take time to describe, but you should do your best to only write enough to get a point across. ADRs are not a dumping ground for your brain, so they should be terse—nothing more, nothing less. While your teammates are ultimately the audience, you should ensure that the bar is low enough that coming back to the ADR in the future means you will read it again.

There are three main tools which help get the point across most easily:

• Words
• Pseudocode
• Diagrams

Avoid over-reliance of one over the other; a long document can evolve into an essay, detailed pseudocode irritatingly becomes a PR, and it can be difficult critiquing specific parts of diagrams for a lack of tooling. There is a delicate balance between all three options and they are very much situational.

Don't Write ADRs For Everything

ADRs should be a curated list of documents representing every large change to a code base, not a record of every change under the sun—we have VCS for that. Don't clog up ADR collections with minor changes; it will make others less willing to read and write them. As a rule of thumb, only use ADRs for significant architectural decisions.

Don’t Overload Individuals

Think about how much effort goes into writing an ADR. You write some thoughts, mull over them, come back over a couple of days, have a few conversations, and then you finally get to cementing your ideas. ADRs are conceptually dense and can be extremely taxing, especially for those with little context.

Be nice to others and don't overburden the same person with your writing. Scattering ADR reviews will help spread high-level knowledge amongst other team members anyway.

There are two soft rules which should serve as a guide:

• If you are very fast (or the ADR small), don't ask the same person to review more than one ADR more than once a week.
• Don't complete another ADR until the implementation of the first is finished.

Only Use Pseudocode for Examples

ADRs should be a place to discuss abstractions, so avoid actual code if at all possible. On the other hand, pseudocode can sometimes be helpful assuming it is abstract. The following are two examples meant to highlight the deceleration of a car:

      #
    # Example 1
    #
    class Car
      def initialize(wheel_count:, color:, deceleration_rate:, make:)
        @wheel_count = wheel_count
        @color = color
        @deceleration_rate = deceleration_rate
        @make = make
        @speed = 0
        @windows_up = true
      end
  
      def roll_down_windows
        @windows_up = false
      end
  
      def roll_up_windows
        @windows_up = true
      end
  
      def stop
        loop do
          tmp_speed = speed - deceleration_rate
          self.speed = tmp_speed < 0 ? 0 : tmp_speed
          break if speed == 0

          sleep 1
        end
      end

      def tune_radio(radio_station)
        @radio_station = radio_station
      end
    end

    #
    # Example 2
    #
    class Car
      def initialize(..., deceleration_rate)
        @deceleration_rate = deceleration_rate
      end

      def stop
        every_second
          decrease_speed_by_deceleration_rate
      end
    end

The second version is clearly the winner: no unrelated methods and no tedious details, the focus of the second example is on the abstractions and only emits details if they are relevant or small.

Also note that the pseudocode follows language style guides. Just like written English, I cannot stress enough how important it is to use "grammatically correct" pseudo-code. If the language constructs of your pseudocode wouldn't make it through your linter, then think twice before having it reviewed. Treat your pseudo-code as real code.

Diagrams, Sometimes

If you find yourself floundering through text and pseudocode, turn to drawing. In times like these, rely on diagrams to illustrate abstract concepts. Diagrams are also extra beneficial for those who struggle with English. Treat diagrams like text and code; they should be reviewed, contain no rough edges, and thought over just like everything else. Additionally, it's worth noting that one of the major drawbacks of diagrams is that reviewing specific parts can be painful, so it's always worth including short textual descriptions of each diagram.

Use Outlines

Tell the reader where they're heading before you take them there with an outline. Doing so builds context, frames the idea, and frees the reader from having to focus on overly specific details.

After an ADR's problem statement, I find it useful to frame the rough draft of an ADR with an index which serves as an outline. The outline acts as a personal writing tool by providing clear direction when I'm writing and a way to step back to observe and compare the index within the general flow and alongside any edits I eventually make. I always leave the outline, however, to give the reader a big picture view before diving into the specifics.

Conclusion

All in all, these rules should carry you and your team far. Moving on from here, you can start creating team-specific templates, guidelines, and launch checklists, whatever makes the smoothest approach to getting well-formed thoughts on paper. If the list of suggestions is at first too long, focus only on practicing a few at a time or at least apply the Golden Rule to reviewing to help you understand what is good and bad. In other words, be nice to your team and your future self. You'll thank yourself later.

A Word of Caution

Poorly written ADRs are not only a waste of time, but will have the opposite effect of what's intended. Trying to decipher the meaning of a poorly written ADR will drive the most patient to the edge of insanity, so if you can't commit to quality ADRs I would personally avoid them altogether. In fact, it is this critique that I see the most often when it comes to writing ADRs. People will say things like "I don't want to have to read bad writing" or "I spend more time correcting or skirting around English skills than the technical ideas." These are both valid critiques and this is why I would not recommend writing ADRs unless you can commit to trying to write them well, otherwise the lack of communication skills will make your worklife a special kind of hell, one where you are wading through grammatical mistakes while trying to understand complex technical ideas.