Course contentsShow
← Software Engineering
Lesson 1702 of 1,93349. Technical Writing and DocumentationFree lesson

Documenting Alternatives Considered

Capture rejected options and why they were dismissed to preserve decision rationale for future teams.

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."