Ga naar inhoud

Documentatie bijdragen

Handleiding voor wie docs in de bron-repository (of parallel in VSA-tooling) wijzigt: TermRefs, tabellen, lokale builds en wat CI controleert.

Scripts (bron)

Script Wanneer
serve Snelle lokale preview zonder glossary/TermRef-hover
serve-tev2 Preview met TEv2 (zoals CI) — herhaal na term-/TermRef-wijzigingen
build --no-tev2 Alleen mkdocs build --strict (geen TEv2)
build Volledige keten: TEv2 + TermRef-check + mkdocs build --strict (= CI-parity) 
cd /d C:\Git\orthodox-ronl\bron
npm install
serve-tev2

TEv2-tools: pins in root-package.json (@tno-terminology-design/* 1.2.0). Voorkeur: npm install (lokaal node_modules), niet alleen globale installs.

serve / build --no-tev2 tonen geen opgeloste TermRefs; gebruik serve-tev2 / build als je hover of glossary wilt controleren.

TermRefs

  • Org-termen: [zangstuk](@) in bron; in VSA-tooling bij voorkeur [zangstuk](@bron) tenzij de tool-repo een bewuste lokale herdefinitie heeft.
  • Na TRRT mogen geen […](@…)-vormen meer in generated/docs staan — CI draait python scripts/check-tev2-termrefs.py generated/docs.
  • Beleid: schrijfconventies (TermRefs + synoniemen).

Markdown-tabellen

Kolommen in de bron aligneren (spaties). Bulk:

cd /d C:\Git\orthodox-ronl\VSA-tooling
python scripts\align_markdown_tables.py ..\bron\docs\

Cursor-regel: .cursor/rules/markdown-table-layout.mdc.

Versie-pins (docs-stack)

Onderdeel Pin / range Bestand
MkDocs Material >=9.5,<10 requirements-docs.txt
git-revision-date plugin >=1.2 requirements-docs.txt
TEv2 CLI’s (trrt/hrgt/mrgt/mrg-import) 1.2.0 package.json

Houd pins gelijk tussen bron en VSA-tooling tenzij er een bewuste drift-PR is.

VSA-tooling

Zelfde scriptnamen; mrg-import is daar standaard (bron-MRG voor *@bron). Zie TEv2 in tool-docs.

Checklist vóór PR

  • [ ] build groen (of CI docs-pages / docs-build)
  • [ ] Type + publiek benoemd (of evident uit hub/pad): zie schrijfconventies — paginatypen / persona’s
  • [ ] Lezerstest voor dat type: kan de beoogde lezer in één scan antwoorden op voor wie / wanneer / wat moet ik doen of weten? (hub = route; task = stappen + voorbeeld; term = waartoe; CLI = SYNOPSIS-achtig + foutpad)
  • [ ] Nieuwe/gewijzigde termen: curated text + TermRefs waar de term voorkomt (term-sjabloon; jargon alleen via glossary)
  • [ ] Jargon op de pagina → TermRef of expliciet “niet in glossary” (geen ad-hoc term)
  • [ ] Pagina voldoet aan schrijfconventies: kopnorm (voor wie / wanneer / antwoord eerst), toon welwillende volwassene tenzij docs-/tool-contributor of spec-/PR-reviewer; task/CLI/workflow hebben foutpad; lezerstekst gebruikt persona-namen (geen kale P3)
  • [ ] Frontmatter waar van toepassing: doc_type + audience als P3 — Notatie-auteur (niet alleen P3)
  • [ ] Nagelezen als de bedoelde lezer: zou iemand zonder voorkennis begrijpen wat je bedoelde?- [ ] Tabellen uitgelijnd
  • [ ] Geen afgeleide SVG/MXL in bron committen