Documenting Alternatives Considered
You'll learn why capturing rejected options in technical documentation preserves critical decision context that prevents teams from relitigating settled questions.
The Problem of Forgotten Options
When teams make technical decisions, they often explore multiple approaches before settling on one. Without documentation, future engineers revisit the same options, unaware they've already been evaluated and dismissed. It's like wandering in circles without a map showing "dead ends already explored."
What to Document
When writing ADRs or design documents, explicitly list alternatives you considered but rejected. For each option, briefly explain:
- What it was: A clear description of the alternative approach
- Why it seemed viable initially: Its potential benefits
- Why you dismissed it: Specific technical, cost, or contextual reasons
Example Format
## Alternatives Considered
### Option 1: Use Redis for session storage
- Pros: Fast, well-known, team expertise
- Cons: Adds infrastructure dependency, session data exceeds 512MB limit
- Dismissed because: Our session payloads regularly exceed Redis string limits
### Option 2: PostgreSQL with connection pooling
- Pros: Already in stack, ACID guarantees
- Cons: Slower than in-memory solutions
- Dismissed because: Latency requirements under 10ms not consistently achievable
Why This Matters
Six months later, a new engineer suggests "Why don't we use Redis?" Your documentation immediately answers this without requiring the original architects to explain again. You've saved investigation time and preserved institutional knowledge through team turnover.
Key Takeaway: Documenting rejected alternatives turns ephemeral team discussions into permanent decision artifacts that prevent redundant exploration and explain the "why not" as clearly as the "why."