Naar hoofdinhoud gaan

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):
  1. Frontmatter: title (identiek aan hoe het in de sidebar heet, zonder “Artikel N”)
  2. Clausules als #### Kop + één korte alinea
  3. Geen proza-inleiding; geen afsluitende conclusie
  4. 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
Snippet-file conventie:
Nieuwe snippets: pure markdown in body, geen JSX. Metadata gaat in frontmatter.

Compleet voorbeeld

  • Live pagina = alleen banner + download-link (geen inline render, anders duplicatie in search)
  • scripts/build-voorbeeld.mjs genereert één .md vanuit een template in scripts/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.mjs resolvet snippets (verbatim) en schrijft per product × taal geresolveerde artikel-.md’s + een manifest.json naar dist/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 in docs.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/...
Laatst gewijzigd op 6 november 2026