2024-11-03 · Elena Voronova

Documenting Rejected Options

Architecture decisions fail socially when only the winner is recorded. Future readers assume the chosen path was obvious.

We teach a rejected-options section in every ADR: option name, why it was viable, why it lost, and what would change the decision. This cuts repeat debates by half in teams we follow up with.

Keep graveyard entries short — three bullets max. Link to tradeoff matrices when scores exist. Supersede old rejections when constraints change; do not delete them.

The ADR Workshop Intensive dedicates week two entirely to this habit. Participants report fewer circular reviews within a month.

#documentation #ADR