Documentatie bijdragen

Documentatie woont naast de code: één PR, één review, samen gemerged. Deze pagina legt uit waar nieuwe documentatie thuishoort.

Vier secties (Diátaxis-light)

Sectie	Doel	Lezer wil
how-to/	Taakgerichte gidsen	Iets uitvoeren
reference/	Feiten en specs	Een feit opzoeken
explanation/	Achtergrond en context	Iets begrijpen
adr/	Architectuurbeslissingen	Weten waarom iets zo besloten is

releases/ bevat klant-release-notes per versie en wordt automatisch gevuld door de release-flow (zie release-docs workflow).

Welke sectie kies ik?

Stel jezelf één vraag: wat doet de lezer met deze pagina?

• “Stappen volgen om iets te doen” → how-to/
• “Een waarde, naam of contract opzoeken” → reference/
• “Iets begrijpen of een mentaal model bouwen” → explanation/
• “Vastleggen waarom we deze technische keuze maken” → adr/

Twijfel? Begin in explanation/, splits later op als de pagina te lang wordt.

Werkwijze per PR

1. Wijzig je gedrag dat een teamlid of klant moet weten? Update of voeg een doc toe in dezelfde PR.
2. Maak je een architectuurkeuze? Maak een ADR met npm run docs:adr -- "korte-titel".
3. Het PR-template heeft een sectie “Documentatie”: vul daar kort in welke docs zijn aangepast, of vink “geen docs nodig” aan met reden.
4. De docs-check workflow plaatst een waarschuwingscomment als productie-code is gewijzigd zonder enige docs/** aanpassing. Het is een waarschuwing, geen blocker.

Schrijfstijl

Nederlandse user-facing copy. Geen em-dashes (gebruik komma’s of haakjes). Houd zinnen kort en concreet.

Niet linken naar _legacy/

docs/_legacy/ bevat oude documentatie die wordt opgeschoond. Verwijs niet vanuit nieuwe docs.