How do you make and document significant technical decisions?

Question

Accepted Answer

Significant technical decisions should be **deliberate, transparent, and recorded**, not made in someone's head and forgotten. A good process surfaces trade-offs, builds buy-in, and leaves a trail so future engineers understand *why*, not just *what*.

## A decision framework

```text
1. FRAME the problem and the constraints (cost, time, team skill, scale)
2. LIST the realistic options — usually 2-4, including "do nothing"
3. EVALUATE each against the constraints and trade-offs
4. DECIDE, and state the reasoning explicitly
5. RECORD it (ADR) and communicate it
6. REVISIT if assumptions change
```

## Record it with an ADR

An **Architecture Decision Record** is a short, durable note:

```markdown
# ADR 014: Use PostgreSQL for the new service

## Status: Accepted

## Context
We need a primary datastore. Team knows SQL; data is relational; scale is moderate.

## Decision
Use PostgreSQL.

## Consequences
+ Strong consistency, team familiarity, rich querying.
- Vertical scaling limits later; revisit if write volume 10x's.

## Alternatives considered
DynamoDB (rejected: relational data, team unfamiliar).
```

## The trade-off to manage

Documenting everything is overhead; documenting nothing loses institutional memory. Reserve ADRs for decisions that are **costly to reverse** or that future engineers will question.

## Why it matters

Undocumented decisions get re-litigated endlessly, every new engineer re-asks "why did we pick this?"

Writing the reasoning down also forces clarity: if you can't justify it on paper, you probably haven't thought it through.