Decision-making glossary
Decision record
A decision record is a short document that captures one decision in full: the question, the context, the options considered, the choice made, the reasoning, and the expected consequences. Where a decision log lists many decisions briefly, a decision record explains a single decision in enough depth that someone new can understand it years later.
Decision records became common in software through the architecture decision record, but the format suits any decision worth explaining: a pricing change, a vendor choice, a policy. The usual sections are a title, a status, the context, the decision and its consequences. Records are numbered and kept together, and the collection becomes a decision log.
The rule that matters is that a record is not edited to fit what happened later. If the decision changes, write a new record and mark the old one superseded, with a link to its replacement. That keeps the original reasoning intact, which is the only way to find out whether it was sound.
Common mistakes are writing the record weeks later from memory, leaving out the options that were rejected, and letting it grow into a design document. One or two pages is enough.
In Decize: Each decision in Decize is one record with an owner, a deadline, reversibility, a confidence and forecast, and later an outcome and a lesson. See how →
Sources: Michael Nygard, “Documenting Architecture Decisions” (2011) · Architectural Decision Records (adr.github.io)