Hoe maak en documenteer je significante technische beslissingen?

Question

Accepted Answer

Significante technische beslissingen moeten **opzettelijk, transparant en geregistreerd** zijn, niet in iemands hoofd gemaakt en vergeten. Een goed proces maakt afwegingen zichtbaar, creëert draagvlak en laat een spoor na zodat toekomstige engineers begrijpen *waarom*, niet alleen *wat*.

## Waarom het belangrijk is

```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
```

## Leg het vast met een ADR

Een **Architecture Decision Record** is een korte, duurzame notitie:

```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).
```

## De afweging om te beheren

Alles documenteren kost veel tijd; niets documenteren verliest institutioneel geheugen. Reserveer ADR's voor beslissingen die **duur zijn om ongedaan te maken** of waarover toekomstige engineers vragen zullen hebben.

## Waarom het belangrijk is

Ongedi-umenteerde beslissingen worden eindeloos opnieuw bekeken, elke nieuwe engineer vraagt weer "waarom hebben we dit gekozen?"

De redenering opschrijven dwingt ook helderheid af: als je het op papier niet kunt rechtvaardigen, heb je het waarschijnlijk niet goed doordacht.