A team writes architecture decision records that nobody reads. What makes an ADR useful, and what should it deliberately not contain?

What makes it useful

The rejected options and why they were rejected. That is the content nothing else carries: the code shows what was chosen, and the only irreplaceable information is what was considered and dismissed, and on what grounds.

An ADR that lists a decision and its benefits is a justification. One that says "we considered X and rejected it because of Y, which we may need to revisit if Z changes" is a decision record, and it is what allows someone in two years to reopen the question intelligently.

The structure that works

• Context: what forced the decision, and what constraints applied at the time.
• Options considered, with the genuine trade-off of each — including the one that was nearly chosen.
• The decision, stated plainly.
• Consequences, including the bad ones. An ADR with no negative consequences listed is not credible and reads as advocacy.
• The conditions that would make this wrong, which is the most valuable and least written section, because it tells a future reader what to watch for.

What it should not contain

• Implementation detail, which changes and belongs in code.
• A description of the current architecture, which will be stale.
• Consensus language. An ADR recording that everyone agreed conceals the disagreement that is the most useful signal in it. Recording a dissent with its reasoning is more valuable than recording agreement.

Why they go unread, and the fix

They are unread because they are unfindable and because nobody knows one exists for the question they have.

The fix is placement and linking: ADRs in the repository next to the code they govern, referenced from the code where the decision is visible, and indexed by the question they answer rather than by number. A reader looking at an odd-looking retry policy should find the ADR from the code, not by searching a wiki.

The property that makes them uniquely durable

An ADR is never stale, because it was always historical. It describes a decision at a moment with the information available then. That is why it is the highest-value-per-word architecture artefact and why it survives when current-state documentation does not.