Skip to content
BENIBIX Learn

Architecture Decision Record vs Design Doc

People think an architecture decision record is just a short design doc. A design doc plans a whole change before the code is written, and is read and argued over. A decision record saves one choice and the reasons, at any time, in a few lines. Design docs often go stale once the work ships. Decision records are kept for good, and a new one replaces an old one.

Development🏗️ Architecture

Architecture Decision Record (ADR)

A short note that saves one design choice and why the team made it.

An architecture decision record is a short note that saves one big design choice and the reasons for it. It says what the problem was, what the team chose and what follows from that choice. Each record covers one decision and gets a number. The records live with the code, often as Markdown files in a docs folder. Michael Nygard made the idea popular in a blog post in 2011.

Example
Emma's team picks PostgreSQL over MongoDB. She writes record number 7 with the reasons, so a new developer a year later knows why.
Why it matters
Teams forget why things are the way they are. A record stops the same argument from coming back again and again.
Full entry
Development🏗️ Architecture

Technical Design Document

A written plan for a new part of an app. The team reads it before coding.

A technical design document is a written plan for building a feature or system before the coding starts. It says what problem it solves and what is left out. It shows the design, often with diagrams, and the other options that were turned down. Teammates read it and leave comments. Many teams write one for any large change.

Example
Before building search, Jack writes a six-page design doc. A reviewer sees the index will not fit in memory. The plan changes in a day, not a month.
Why it matters
Mistakes are cheapest to fix on paper. The doc also tells later readers what was built and why.
Full entry

In one line

Architecture Decision Record (ADR)
A short note that saves one design choice and why the team made it.
Technical Design Document
A written plan for a new part of an app. The team reads it before coding.