Over de Nederlandse Richtlijn Digitale Systemen Contact en bijdragen Versies Toegankelijkheid Privacy Copyright Cookies Kwetsbaarheid melden

Bijdragen aan de Nederlandse Richtlijn Digitale Systemen

Allereerst, bedankt dat je de tijd hebt genomen om een bijdrage te leveren! ❤️

We waarderen alle soorten bijdragen enorm. Zie die Inhoudsopgave voor verschillende manieren waarop je kan bijdragen aan de Nederlandse Richtlijn Digitale Systemen (NeRDS). Zorg ervoor dat je de relevante hoofdstukken even leest voordat je een bijdrage levert. Het zal het voor het team van de NeRDS een stuk makkelijker maken en de ervaring voor alle betrokkenen soepeler laten verlopen. We kijken uit naar alle bijdragen! 🎉

Het ontwikkelen van de NeRDS via GitHub is een bewuste keuze voor transparantie en samenwerking. We werken systematisch aan verschillende bouwblokken en prioriteren deze op basis van waarde en urgentie. Hierdoor kan het voorkomen dat reacties op suggesties of toevoegingen enige tijd vergen, vooral bij onderwerpen die later op de planning staan. We waarderen alle bijdragen en streven ernaar om feedback zo snel mogelijk te verwerken.

Inhoudsopgave

Voor je begint

Manieren om bij te dragen

Ontwikkeling

Technische richtlijnen

Code of Conduct

Dit project en iedereen die eraan deelneemt, valt onder de Code of Conduct op GitHub. Door deel te nemen, wordt van je verwacht dat je je aan deze code houdt. Meld onacceptabel gedrag aan bureau.architectuur@minbzk.nl.

Ik heb een vraag

Maak een issue aan

Voordat je een Issues gaat aanmaken, kan je bekijken of jouw vraag al tussen de bestaande Issues staat. Wellicht staat er al een issue tussen die jou vraag kan beantwoorden.

Als je jouw vraag nog steeds wilt stellen, kan je een Issue aanmaken.

  1. Gebruik daarvoor de knop new issue.
  2. Formuleer je vraag of opmerking en geef een heldere toelichting.
  3. Anderen kunnen nu opmerkingen toevoegen aan jouw issue.
  4. Het team van de NeRDS zal deze issue labelen als question en pakt jouw issue zo snel mogelijk op. Mogelijk neemt het team van de NeRDS contact op voor een verduidelijking of een oplossing.

Stel een vraag via mail

Je kan je vragen ook altijd stellen door een mail te sturen naar bureau.architectuur@minbzk.nl.

Ik wil een fout of bug melden

Heb je een foutje gevonden in de NeRDS? Dan kan je deze melden door een Issue aan te maken.

Voordat je een Issues gaat aanmaken, kan je bekijken of jouw gevonden fout al tussen de bestaande Issues staat.

Als je de gevonden fout nog steeds wilt melden, kan je een Issue aanmaken.

  1. Gebruik daarvoor de knop new issue.
  2. Beschrijf de fout duidelijk en geef een heldere toelichting. Voeg waar mogelijk een screenshot toe.
  3. Het team van de NeRDS zal deze issue labelen als bug en pakt jouw issue zo snel mogelijk op. Mogelijk neemt het team van de NeRDS contact op voor een verduidelijking of een oplossing.

Ik wil een verbetering voorstellen

Wanneer je bijdraagt aan dit project, moet je ermee akkoord gaan dat je 100% van de inhoud hebt geschreven, dat je de benodigde rechten op de inhoud hebt en dat de inhoud die je bijdraagt mag worden geleverd onder de Code of Conduct.

Heb je een suggestie of wil je een verbetering voorstellen? Dat kan gaan om een compleet nieuwe functionaliteit van de site of om kleine verbeteringen. Het volgen van onderstaande instructie helpt het team van de NeRDS om je suggestie te begrijpen en gerelateerde suggesties te vinden.

Je kan een suggestie doen door een Issue aan te maken of door een Pull Request te maken.

Voordat je een suggestie gaat maken

  • Voordat je een suggestie gaat maken, kan je bekijken of jouw suggestie al tussen de bestaande Issues staat. Wellicht bestaat er al een issue die jouw suggestie beschrijft, en zijn we er al mee bezig.
  • Zoek uit of jouw idee past binnen het doel en de scope van het project. Wat zijn de voordelen van deze functionaliteit of toevoeging? Het is aan jou om het team van de NeRDS en de community te overtuigen dat dit een nuttige toevoeging is aan de NeRDS. Houd in gedachten dat we functionaliteiten willen die nuttig zijn voor de meerderheid van onze gebruikers en niet slechts voor een kleine groep.

Een issue aanmaken

Als je jouw suggestie nog steeds wilt doen, kan je een Issue aanmaken.

  1. Gebruik daarvoor de knop new issue.
  2. Beschrijf duidelijk jouw suggestie en geef een heldere toelichting en onderbouwing waarom dit een goede toevoeging zal zijn aan de NeRDS
  3. Het team van de NeRDS zal deze issue labelen als enhancement en pakt jouw issue zo snel mogelijk op. Mogelijk neemt het team van de NeRDS contact op voor een verduidelijking of een oplossing.

Afhankelijk van de complexiteit en het onderwerp van jouw suggestie kan het even duren voordat deze wordt opgepakt door het team van de NeRDS.

Een pull-request maken

Kun je niet uit de voeten met de issues? Bijvoorbeeld omdat je verschillende wijzigingsvoorstellen wilt doen? Je kan ook gebruik maken van een Fork en een Pull Request.

Hoe we werken op Github

We werken met Markdown bestanden. Dit is bestandsformaat voor platte tekstbestanden en wordt door veel verschillende tools ondersteund. Dit maakt het eenvoudig om versiebeheer op de NeRDS toe te passen.

Daarnaast maken gebruik van mkdocs en het NLDD Designsysteem om de informatie op een interactieve wijze inzichtelijk te maken op de website van de NeRDS.

Ontwikkelomgeving opzetten

Uitgebreide ontwikkelomgeving

Voor bijdragen aan de NeRDS heb je een lokale ontwikkelomgeving nodig:

  1. Installeer uv

  2. Start de development server

uv run mkdocs serve

uv installeert bij de eerste keer zelf de juiste Python en de afhankelijkheden.

  1. Bekijk je wijzigingen Open http://localhost:8000 in je browser

  2. Controleer je wijzigingen

uv run python scripts/check_site.py

Dit bouwt de website en controleert de opmaak tegen het designsysteem. Pas je het thema in src/theme aan, draai dan ook just a11y voor de toegankelijkheidscontrole (WCAG 2.1 AA). Beide controles draaien ook op elke pull request.

Wil je een nieuwe pagina aanmaken?

In het mkdocs.yml bestand staan de settings voor deze website. In richtlijn hoef je hier niets aan aan te passen, maar als je een nieuwe pagina wilt aanmaken kan het nodig zijn om hier een aanpassing in te doen. Onderdeel van deze settings is namelijk de navigatie voor de site (welke pagina's zijn zichtbaar, en welke pagina's vallen daaronder). Dit staat in de nav: sectie. Indien je een nieuwe pagina wilt toevoegen, is het vaak nodig deze wijziging ook door te voeren in het mkdocs.yml bestand.

Een nieuwe richtlijn krijgt bovenaan de pagina een title, een summary en een icon. De kaarten op de startpagina en op het overzicht van richtlijnen worden daaruit opgebouwd. Voor icon kies je een naam uit de iconen van het NLDD Designsysteem; een naam die niet bestaat laat de controle hierboven falen.

Richtlijnen voor bijdragen

Inhoud schrijven

  • Taal: Schrijf in correct Nederlands
  • Tone of voice: Formeel maar toegankelijk, passend bij overheidsstandaarden
  • Structuur: Gebruik duidelijke kopjes en bullet points
  • Lengte: Houd artikelen beknopt en to-the-point
  • Bronnen: Verwijs naar officiële bronnen en standaarden waar relevant

Toegankelijk schrijven

Wie een schermlezer gebruikt, springt van kop naar kop en vraagt een lijst met links op. Daarom:

  • Koppen: Maak van een tussenkopje een echte kop (###), geen vetgedrukte regel. Sla geen niveau over: onder ## komt ###. De controle op je pull request faalt op een overgeslagen niveau.
  • Links: Geef een link een tekst die het doel noemt, ook los van de zin eromheen. Twee links met dezelfde tekst gaan naar dezelfde plek, en één plek heeft overal dezelfde naam. Schrijf dus niet "hier" of "voorkeur", maar "Kamerbrief over de soevereine overheidscloud". Zet bij een bestand het soort erbij: "(pdf)".
  • Andere taal: Zet bij een Engelse titel of zin {: lang="en" } direct achter de link of de vetgedrukte tekst, bijvoorbeeld **The Mom Test**{: lang="en" }. Een voorleesprogramma spreekt het dan Engels uit. Ingeburgerde woorden als "open source" hebben dit niet nodig.

De richtlijnen in de plugin

De plugin voor AI-assistenten bevat per richtlijn een kopie van de tekst, in skills/<naam>/richtlijn.md en fases.md. Die bestanden wijzig je niet zelf. Je wijzigt de richtlijn in docs/richtlijnen/, en het script scripts/generate_plugin.py maakt de kopie opnieuw.

Met pre-commit gebeurt dat vanzelf bij je commit. Zonder pre-commit draai je just plugin. Een controle op de pull request faalt als de kopie achterloopt.

Afbeeldingen en media

  • Plaats afbeeldingen in de juiste assets/ map
  • Gebruik beschrijvende bestandsnamen
  • Voeg altijd alt-tekst toe voor toegankelijkheid

Branching strategie

Gebruik kebab-case, houd de namen kort maar beschrijvend en vermijd speciale karakters. Branch types:

  • main: Productie-ready code
  • feat/beschrijving: Nieuwe functionaliteit
  • fix/beschrijving: Bug fixes
  • docs/beschrijving: Documentatie updates

Versies en releases

De NeRDS heeft één versienummer, in de vorm major.minor.patch. De website en de plugin voor AI-assistenten dragen hetzelfde nummer als de richtlijn. Dat nummer staat in pyproject.toml. Je wijzigt het niet met de hand.

De titel van je pull request

Een pull request gaat als één commit naar main (squash), met de titel van de pull request als titel. Die titel komt in het overzicht van versies op de website (onder "Over NeRDS"). Begin de titel met een van deze drie voorvoegsels:

  • feat: voor een nieuwe richtlijn, een inhoudelijk gewijzigde richtlijn of een nieuwe functie van de website of de plugin. De volgende versie krijgt een hoger middelste cijfer.
  • fix: voor een correctie: een typfout, een dode link, een fout in de website. De volgende versie krijgt een hoger laatste cijfer.
  • chore: voor onderhoud waar een lezer niets van merkt, zoals een update van een afhankelijkheid. Dit komt niet in het overzicht.

Schrijf de rest van de titel zo dat een lezer van de richtlijn hem begrijpt. Bijvoorbeeld: feat: cloud-richtlijn in lijn met het cloudbeleid van 2026.

Een controle op de pull request weigert een titel zonder voorvoegsel.

Een versie uitbrengen

Dit doet het NeRDS-team. Op GitHub staat steeds één pull request open met de naam "release", die release-please bijhoudt. Daarin staan het volgende versienummer en de regels voor het overzicht van versies, opgebouwd uit de titels sinds de vorige versie.

Het team brengt een versie uit door die pull request te mergen. De tag, de release op GitHub en de uitrol van de website volgen vanzelf. De plugin krijgt hetzelfde nummer, zodat wie hem heeft geïnstalleerd de nieuwe inhoud ontvangt.

Tussen twee versies kan de website al wijzigingen tonen die nog niet zijn uitgebracht. De pagina Huidige versie laat zien welke build er precies draait.

Laatst bijgewerkt: 29 oktober 2026

Helpt u ons door uw feedback te delen? We gebruiken dit om NeRDS te verbeteren. U kunt feedback geven via e-mail of via GitHub Issues.

Een soort feedback is nodig. Minimaal 10 tekens. Maximaal 5000 tekens.