Drafting: anatomie en regels
Interne richtlijn voor hoe we Voorwaarden opbouwen. Korter is beter.Hiërarchie
- Artikel = één verantwoordelijkheid. Als een artikel “X en Y” heet, splits.
- Clausule = één regel. Eén kop (
####), één gedachte. Combineer niet. - Termen krijgen hun definitie in Artikel 1 en worden overal hetzelfde gespeld (hoofdletter voor gedefinieerde termen:
Uitgever,Optiehouder).
Typografie
- Geen emdashes (
—) of en-dashes (–). Gebruik komma’s, dubbele punten of haakjes voor de bijzin. Reden: oogt AI-gegenereerd en is lastig te typen voor co-auteurs. - Geen smart quotes in nieuwe tekst (
"i.p.v." ").
Terminologie (overal gelijk)
Nieuw concept? Kies eerst een term die al elders gebruikt wordt. Alleen nieuw invoeren als echt nodig.
Artikel-patroon
Elk artikel-bestand (<instrument>/voorwaarden/<artikel>.mdx):
- Frontmatter:
title(identiek aan hoe het in de sidebar heet, zonder “Artikel N”) - Clausules als
#### Kop+ één korte alinea - Geen proza-inleiding; geen afsluitende conclusie
- Verwijzingen naar andere artikelen: markdown-links, geen MDX-magie
Snippets (her)gebruik
Opties gebruikt modular snippets in/snippets/<artikel>/<slug>.mdx. Waarom:
- Compleet voorbeeld is gegenereerd uit dezelfde snippets → geen inhoud dupliceren
- Varianten (good leaver / bad leaver / etc.) kunnen later naast elkaar bestaan zonder copy-paste
Compleet voorbeeld
- Live pagina = alleen banner + download-link (geen inline render, anders duplicatie in search)
scripts/build-voorbeeld.mjsgenereert één.mdvanuit een template inscripts/templates/die de snippets importeert- Template wijzigt mee met de artikelstructuur; regenereer na wijzigingen
Clause-bank artefact (voor externe consumenten, bv. de drafter op app.belang.org/tooling/documents)
scripts/build-clauses.mjsresolvet snippets (verbatim) en schrijft perproduct × taalgeresolveerde artikel-.md’s + eenmanifest.jsonnaardist/clauses/(gitignored; build-only artefact).- Product/taal/artikel-volgorde komt uit
docs.json(zelfde nav als de site), dus het loopt niet uit de pas met wat gepubliceerd wordt. - Bron van waarheid blijft de MDX hier; consumenten pinnen een versie
(
manifest.banks[].version/hash+sourceCommit) en pullen het artefact. - Body’s worden VERBATIM gesliced (geen markdown-reparse), zodat notatie in de clausule-tekst exact meekomt.
Nummering
Artikel-niveau:## Artikel N - Titel (alleen in de template).
Clausule-niveau: #### Titel (snippets) of #### N.M Titel (alleen in template, met nummering).
Redirects
Hernoem je een pad? Voeg een redirect toe indocs.json onder "redirects". Nooit stilletjes verplaatsen.
Wat we (nu) niet doen
- Geen versie-tags per clausule (komt later, zie data-structuur discussie)
- Geen varianten in één snippet; elke variant krijgt zijn eigen snippet-file
- Geen taal-specifieke content in snippet-bodies; vertalingen in
/snippets/en/...