Kuinka teet ja dokumentoit merkittäviä teknisiä päätöksiä?

Question

Accepted Answer

Merkittävät tekniset päätökset pitäisi tehdä **harkitusti, läpinäkyvästi ja dokumentoiden**, ei jonkun päässä ja sitten unohtaa. Hyvä prosessi tuo esille kompromissit, rakentaa yhteisymmärrystä ja jättää jäljen, joten tulevat insinöörit ymmärtävät *miksi*, ei vain *mitä*.

## Päätöksentekokehikko

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

## Dokumentoi se ADR:llä

**Architecture Decision Record** on lyhyt, pysyvä muistiinpano:

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

## Hallittava kompromissi

Kaiken dokumentointi on lisäkustannusta; mitään dokumentoimatta jättäminen menettää organisaation muistin. Varaile ADR:t päätöksille, joita on **kalliiksi kumota** tai joita tulevat insinöörit tulevat kyseenalaistamaan.

## Miksi se on tärkeää

Dokumentoimattomat päätökset käydään läpi loputtomasti, jokainen uusi insinööri kysyy "miksi valitsimme tämän?".

Perustelun kirjoittaminen alas pakottaa myös selkeyteen: jos et voi perustella sitä paperilla, et luultavasti ole ajatellut sitä tarpeeksi.