Recording why.
WHY IT MATTERS
Architecture decisions are questioned for years, and the reasoning is forgotten within months.
WHAT HAPPENS WITHOUT RECORDS
Decisions reversed without understanding why they were made The same discussions repeated Constraints violated because nobody knew they existed
WHAT A DECISION RECORD CONTAINS
The context: what situation prompted it
The decision The alternatives considered The consequences, good and bad The status
WHAT TO KEEP THEM AS
Short. One page.
WHERE TO KEEP THEM
With the code, in version control.
WHY
So they are found, and so their history is visible.
WHAT TO RECORD
Anything expensive to reverse Anything where the reasoning is not obvious Anything someone will question
WHAT NOT TO RECORD
Routine choices.
WHAT TO DO WHEN A DECISION IS SUPERSEDED
Write a new record, marking the old one superseded.
WHY NOT DELETE
The history explains how the system arrived where it is.
WHAT ELSE TO DOCUMENT
A diagram showing the parts and how they communicate.
