# 4 Reasons Why You Should Write Architecture Decision Records (ADR)
We make decisions all the time. And some decisions are harder than others. Some decisions have long term effects. And some are more ephemeral.
While not all decisions require the same level of deliberation, the architecture plan of a piece of software can mean the difference between glorious success or crippling failure.
Architecture Decision Records (ADR) are powerful decision making tools that force you to think deeper and avoid haphazard and flawed decisions. In this article, I'll detail four reasons why writing ADR will improve your decision making.
This article assumes you already know what an ADR is. If you're brand new to ADR, see the following resources:
- Documenting Architecture Decisions - Michael Nygard
- Creating a Decision Journal: Template And Example Included - Farnam Street
- ADR GitHub organization
- Architecture decision record (ADR) - joelparkerhenderson
- ADR Tools
# The Four Reasons
# 1 Writing is Thinking
By writing your decision, your thinking will improve. Writing organizes your thoughts.
...when you connect your ideas into a written piece, you give voice and direction to something that otherwise just rattles around in the form of entrenched habits and beliefs...1
According to Scott H. Young, writing is not just about putting thoughts in your journal so you can bask in the warm light of nostalgia when you stumble upon it in your garage years later. "Writing doesn’t record your thoughts, it is your thinking".2
It's no surprise that Amazon requires employees to write six page memos instead of creating PowerPoint presentations. This is because long form writing requires heightened thought and mental processing.
Writing memos forces his (Jeff Bezos) team to think through their ideas in high-resolution detail. Instead of wasting time with impromptu brainstorming sessions, writing memos ensures that group discussion is based on the critical review of the relevant ideas, not on hypotheticals.3
# 2 Your Product is Your Decisions
Most decision making in the workplace is haphazard—following a trial-and-error approach. Far too little data is gathered. And that lack of data means you cannot analyze your previous decisions.4
Who you and your organization are today is a result of the decisions you've made.
In most organizations today, your product is decisions. By and large, your success will be the sum of the decisions you make over your career. The problem is it’s not easy to get better at making decisions.5
If this is true, why not have a robust and well tested process to make decisions? Why leave it up to chance? Why sit around making decisions on a whim hoping to get lucky? A robust decision making process is the right approach.
Most organizations don’t use a consistent process or framework to make important decisions. Yet we know that the process by which you come to a decision is the most important thing. It’s not about more information. Process matters more than the analysis. We also know that when you don’t use a consistent process you make it hard to improve.6
By writing down your decisions, you are gathering data that you can use to analyze your decision making and the decisions themselves. That data can then be used to improve your process—thereby improving your future decisions.
A decision journal helps you collect accurate and honest feedback on what you were thinking at the time you made the decision. This feedback helps you see when you were stupid and lucky as well as when you were smart and unlucky. Finally, you can get the feedback you need to make better decisions.5
# 3 Recording Decisions is Knowledge Sharing
When you write down your decisions, you create shareable knowledge that can benefit others. And knowledge sharing has huge consequences.
...firms with a high-trust environment, where employees can collaboratively and transparently share knowledge, gain stock returns two to three times higher than the industry average and have 50% lower turnover rates than competitors. An ineffective knowledge sharing culture, on the other hand, can cost large U.S. firms up to $47 million in lost productivity annually.7
Knowledge silos mean that your decision is isolated—cut off from outside feedback. By creating an ADR, you help break down harmful silos and turn the decision into sharable knowledge.
An example of knowledge sharing in software engineering is the code review.8 Writing an ADR and submitting it for review reaps the following rewards:
- The code review submitter must share knowledge in order to gain the code reviewer's approval—the reviewer may also share knowledge to bolster and improve the ADR
- Once the ADR is improved, it becomes an artifact—sharable across the organization
Both the process by which you write ADR and the ADR itself is knowledge sharing.
# 4 “There are no solutions, only trade-offs"
When making decisions, we naturally pick ones that we like and understand ("intuitively favor").9 Worse yet, we can easily be lead to believe that our decision will completely solve the problem.
However, there is no perfect decision—“there are no solutions, only trade-offs".10 All decisions have advantages and trade-offs.
Writing ADR can help you avoid Pollyannish because you must spell the advantages and trade-offs. And even if you make a bad decision, writing an ADR will help you and others understand why in hindsight.
Writing ADR deepens your thinking. It provides a process that improves your decision making over time. It creates shareable knowledge. And it helps you avoid Pollyannish thinking by evaluating advantages and trade-offs.
- 1Sally Kerrigan, Writing Is Thinking, A List Apart
- 2Scott Young, How to Think Better
- 3Ben Bashaw, How Jeff Bezos Turned Narrative into Amazon's Competitive Advantage, Slab
- 4Morgan D. Jones, The Thinker’s Toolkit, 14 Powerful Techniques for Problem Solving, 9
- 5Creating a Decision Journal: Template And Example Included, Farnam Street
- 6Your Product is Decisions, Farnam Street
- 7Zhou (Joe) Jiang, Why Withholding Information at Work Won’t Give You an Advantage, Harvard Business Review
- 8Titus Winters, Tom Manshreck, Hyrum Wright, Software Engineering at Google, 175
- 9Morgan D. Jones, The Thinker’s Toolkit, 14 Powerful Techniques for Problem Solving, 11
- 10Larry J. Prather AND Dan Delich, In flood resilience debate, there are no solutions — only tradeoffs, The Hill