A team writes decision records diligently and nobody reads them. What is wrong with the practice rather than the format?

What is wrong with the practice

1. They are written after the decision, as a record. The value of writing is largely in the thinking it forces — an argument that sounds coherent aloud frequently falls apart when written. A document produced afterwards captures a conclusion without the reasoning that would have improved it.

2. They are not where the reader is. Stored in a separate repository or wiki, discovered only by someone who already knows to look. The person changing a component encounters the code, not the reasoning.

3. They record outcomes rather than arguments. Context, decision, consequences — with no rejected options and no revisit condition, which are the two fields a future reader actually needs.

4. They are too long. A five-page record is skimmed; a one-page argument is read.

What changes it

• Keep them with the code, in the repository, linked from the components they govern, so the reasoning is encountered at the moment it is needed.
• Write before deciding, circulated for comment. The document is then a decision-forcing proposal rather than a minute.
• Include rejected options and why. If an option was rejected for a reason that still holds, re-proposing it wastes a quarter; if the reason has expired, that is the trigger to revisit.
• Include a revisit condition — a measurable threshold, not a date. "Review annually" is theatre; "when the largest tenant exceeds one partition's practical limit" is checkable.
• One page, with detail in an appendix.
• A status — proposed, accepted, superseded — so readers know what they are looking at.

The test

Give a record to someone who was not there and ask what they would do if they wanted to change the decision. If they cannot say what would justify a change, it documents an outcome rather than a decision.

The value that justifies the practice

Inherited decisions become changeable. Without rationale, a future team's only options are superstition or breaking something to find out why it existed — and untouchable decisions accumulate until the architecture is a museum.