SA-301c · Module 1

Trade-off Documentation

4 min read

The most valuable section of an ADR is not the decision. It is the trade-offs. The decision itself is one line: "We chose PostgreSQL." The trade-offs are the institutional knowledge: why PostgreSQL over MongoDB, what capabilities were sacrificed, what risks were accepted, and what conditions would justify revisiting. When a new architect joins the team and asks "why PostgreSQL?" the trade-off documentation answers in five minutes what would otherwise take a two-hour archaeology session through Slack history and meeting recordings.

Do This

  • Document trade-offs as explicitly as the decision itself — "We chose X and accepted Y as a consequence"
  • Quantify trade-offs where possible — "We accept 200ms additional latency in exchange for cross-region availability"
  • Include the evaluation criteria and how each option scored — the scoring makes the decision traceable

Avoid This

  • Document only the winning option — the rejected options and their reasons are half the value of the ADR
  • Use vague trade-off language — "some performance impact" tells the future reader nothing actionable
  • Omit the criteria — without criteria, the decision appears arbitrary even when it was rigorous