Verhouding tot ADRs
ADRs en handboek doen verschillend werk. Geen redundantie, geen autoriteit-conflict — verschillende registers.
Wat een ADR doet
Een ADR (Architecture Decision Record) legt één concrete beslissing vast:
- Status: Draft / Accepted / Superseded
- Datum: wanneer genomen
- Beslisser: wie tekent
- Context: het probleem waarop dit antwoord geeft
- Decision: wat is gekozen
- Why: waarom dit en niet wat anders
- How to apply: hoe geïmplementeerd
- Open punten: wat nog moet
Eén ADR per beslissing. Klein, gefocust, archiefwaardig. Een toekomstige lezer kan zien dat op 2026-05-12 is besloten dat STOP een wettelijke anker-bron is (ADR-0036) — en kan via Superseded-links de hele beslissings-keten reconstrueren.
Wat dit handboek doet
Het handboek bundelt de redenering en de evidence achter een cluster van beslissingen in een doorlopend leesbaar verhaal. Een hoofdstuk over "Manifestatie-laag" trekt ADR-0031 (two-stack FRBR), ADR-0034 (publicatie als Manifestation), en ADR-0037 (instrument-Manifestation + junction) samen tot één coherent stuk. Plus de evidence: welke artikelen uit wet.artikelen welke keuze schragen, welke alternatieven zijn afgevallen, welke discussies de richting hebben bepaald.
Wanneer is iets een ADR, wanneer een handboek-pagina?
| Type informatie | Plaats |
|---|---|
| "We hebben besloten X" | ADR |
| "X past in het grotere plaatje als…" | Handboek |
| "Y is geanker op artikel Z" | Beide — anker in ADR (formeel), redenering + corpus-fragment in handboek |
| "We hebben alternatief A overwogen maar afgevallen omdat…" | Handboek (ADR mag het kort noemen onder Why; het volledige alternatief-verhaal hoort hier) |
| "Op datum X is X gewijzigd naar Y" | ADR (Status: Superseded) — handboek-pagina wordt navenant bijgewerkt |
| "De evidence-tabel die deze keuze ondersteunt" | Handboek |
Wanneer een conflict?
Als een ADR en een handboek-pagina lijken te conflicteren:
- De ADR wint qua status van de beslissing — dat is het formele archief.
- Het handboek wint qua verklarende lezing — als de ADR onduidelijk is, kan het handboek aanvullend uitleggen.
Als de twee inhoudelijk uit-sync raken, is dat een onderhouds-bug. Het handboek moet bijwerken (niet de ADR), want een ADR is "frozen in time" voor zijn beslissings-moment, terwijl het handboek het levende verhaal vertelt.
Verwijzing van handboek naar ADR
Elke handboek-pagina die uit één of meer ADRs voortvloeit, eindigt met een sectie Onderliggende ADRs:
## Onderliggende ADRs
- [ADR-0031 — Two-stack FRBR](https://…/ADR-0031-two-stack-frbr-decisions-and-instruments.md)
- [ADR-0037 — Instrument-stack Manifestation](https://…/ADR-0037-instrument-stack-manifestation-and-expression.md)Verwijzing andersom (van ADR naar handboek-pagina) is niet verplicht — ADRs hebben hun eigen kruisverwijzingen via Implements: / Amends: / Relates to: headers.