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.
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.
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.
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.