One Size Fits All? An Empirical Comparison of ADR Templates regarding Comprehension, Usability, and Ease of Adoption
This paper empirically evaluates five Architectural Decision Record (ADR) templates using expert screening and a controlled experiment to demonstrate that Nygard's template offers superior overall comprehension and usability, providing practitioners with an evidence-based guide for selecting the most effective documentation format.
Original paper licensed under CC BY 4.0 (http://creativecommons.org/licenses/by/4.0/). This is an AI-generated explanation of the paper below. It is not written or endorsed by the authors. For technical accuracy, refer to the original paper. Read full disclaimer
Imagine you are building a massive, complex Lego castle. You and your team make hundreds of tiny decisions along the way: "Should this tower be red or blue?" "Do we use the round bricks or the square ones?" "Why did we decide to put the drawbridge here?"
If you don't write these decisions down, two years later, when a new builder joins the team, they will have no idea why the castle looks the way it does. They might change a red tower to blue, not realizing it was red to match the sunset in the story. This loss of "why" is what the paper calls knowledge vaporization—the invisible steam of forgotten ideas that leaves your project confused and messy.
To stop this, software teams use something called an ADR (Architectural Decision Record). Think of an ADR as a tiny diary entry for a specific building choice. But here's the problem: There are many different "diary templates" available. Some are like a simple postcard with three lines of text; others are like a 20-page legal contract with checkboxes for every possible detail.
The big question this paper asks is: "Is there one perfect template that fits every situation, or do we need different ones for different jobs?"
The Experiment: A Taste Test for Templates
The researchers didn't just guess; they ran a scientific taste test.
Step 1: The Expert Judges
First, two expert architects (the paper's authors) looked at five popular templates. They acted like food critics, rating them on three things:
- Comprehension: Is it easy to read and understand?
- Usability: Is it quick and easy to fill out?
- Adoption: Would you actually want to use this in your daily work?
They narrowed the field down to the two "tastiest" options:
- Nygard's Template: The "Postcard." It's short, simple, and gets straight to the point.
- MADR: The "Detailed Report." It's structured, has more sections, and forces you to think about pros, cons, and alternatives.
Step 2: The Student Chefs
Next, they brought in 33 software engineering students (acting as junior builders). The students were split into two groups and given two different "building challenges" (like deciding how to connect to an outside service or which database to use).
- Group A used the Nygard template for the first challenge and the MADR template for the second.
- Group B did the exact opposite.
This "crossover" design ensured that everyone tried both styles, so the results weren't just about who was better at writing, but about which template was actually easier to use.
The Results: It Depends on Your Situation
The study found that there is no "one size fits all." The best template depends entirely on your context.
1. The "Speed Run" Winner: Nygard
When students needed to write quickly, or when the project was small and agile, they loved Nygard.
- The Analogy: It's like ordering a quick coffee. You walk in, say "Latte," pay, and go.
- Why it won: It was faster to fill out, less confusing, and felt less like "homework." Students felt it was "straight to the point." If you are in a rush or working on a small project, this is your go-to.
2. The "Deep Dive" Winner: MADR
When students had more time, or when the decision felt very important and complex, they preferred MADR.
- The Analogy: It's like a full-course meal with a detailed menu. You have to fill out more fields, but it forces you to think about why you are choosing the soup over the salad.
- Why it won: It reduced ambiguity. Because it had more sections (like "Pros," "Cons," and "Alternatives"), it made the reasoning clearer and less open to misinterpretation. It was better for big, critical projects where you can't afford to be vague.
The Verdict
The paper concludes that choosing a template isn't about picking the "best" one overall. It's about picking the right tool for the job:
- Use the "Postcard" (Nygard) when you are moving fast, the project is small, or you just need to capture the decision quickly without getting bogged down.
- Use the "Detailed Report" (MADR) when the decision is critical, the project is huge, or you need to make sure everyone understands the deep reasoning behind the choice.
The main takeaway is simple: Don't force a complex, detailed template on a quick, small task, and don't use a tiny postcard for a massive, life-or-death decision. Match the template to the size and urgency of your project.
Drowning in papers in your field?
Get daily digests of the most novel papers matching your research keywords — with technical summaries, in your language.