Hoe draag ik een kennisbank-artikel aan?

Heb jij een waardevol artikel voor onze kennisbank? Wij plaatsen hem graag.

Aanleveren

Er zijn verschillende manieren om een kennisbankartikel aan te dragen:

Optie 1: Stuur ons een e-mail

Stuur een e-mail naar developer.overheid@geonovum.nl met het markdown-bestand van jouw artikel.

Optie 2: Maak een Gist en dien een issue in

Je kunt een artikel schrijven in Markdown en deze als een Gist opslaan. Zorg ervoor dat je de Gist openbaar maakt en de link naar de Gist deelt in een issue.

Optie 3: Maak een Pull Request (onze favoriet)

Je kunt een artikel direct als pull request aanbieden. Plaats het bestand in de juiste map onder docs/ (zie Mappenstructuur hieronder).

Als je nog geen lid bent van onze repository, maak dan eerst een fork. Deze fork kun je vervolgens aanbieden als pull request bij ons.

Markdown

• Artikelen worden aangeleverd als Markdown-bestand (.md of .mdx extensie).
• De bestandsnaam is de slug van het artikel, bijvoorbeeld: mijn-artikel-over-oauth.md.

Frontmatter

Elk artikel begint met frontmatter in YAML-formaat. Hierin staan metadata die door de site worden gebruikt:

---
title: "Aan de slag met OAuth 2.0"
description:
  "OAuth 2.0 is een open standaard voor autorisatie die veel wordt gebruikt bij
  de Nederlandse overheid."
image: ./img/oauth-overview.png
content_type: standaard
tags:
  - informatiebeveiliging
  - oauth
---

Description (verplicht)

Het description veld is verplicht. Dit wordt gebruikt in de RSS-feed en als meta-beschrijving voor zoekmachines. Gebruik bij voorkeur de eerste zin van je artikel.

Image (optioneel, aanbevolen)

Het image veld is optioneel maar aanbevolen. Deze afbeelding wordt gebruikt als preview wanneer het artikel wordt gedeeld op sociale media (Open Graph). Plaats de afbeelding in dezelfde map als het artikel of in een img/-submap.

Content type

Het content_type veld bepaalt in welke overzichten het artikel verschijnt en welke sectieopbouw wordt verwacht. Kies het type dat het beste past:

Content type	Gebruik voor
standaard	Specificaties, protocollen, formaten, voorzieningen
tool	Software, validators, editors, linters
tutorial	Stapsgewijze handleidingen
architectuur	Patronen, concepten, ontwerpbeslissingen
richtlijn	Leidraad content (principes en richtlijnen)

Het content_type veld staat los van de tags. Content types mogen niet als tag voorkomen.

Tags

We hanteren een taggingstrategie met 4 lagen:

Laag 1: Content type (geen tag)

Content type is een apart frontmatter veld (zie hierboven), niet een tag. De waarden standaard, tool, tutorial, architectuur en richtlijn mogen nooit als tag voorkomen.

Laag 2: Thema-tags (verplicht, 1-3 per artikel)

Elk artikel moet minimaal 1 en maximaal 3 thema-tags hebben:

Tag	Beschrijving
informatiebeveiliging	Security, authenticatie, encryptie
interoperabiliteit	Data-uitwisseling, API's, standaarden
toegankelijkheid	WCAG, inclusiviteit, UX
privacy	AVG, gegevensbescherming, logging
infrastructuur	Kubernetes, deployment, cloud
front-end	UI, design systems, libraries
open-source	Licenties, community, governance

Laag 3: Onderwerp-tags (optioneel, 0-5 per artikel)

Specifieke technologieën, standaarden of concepten. Voorbeelden: oauth, oidc, kubernetes, docker, react, dcat, wcag, haven.

Laag 4: Organisatie-tags (optioneel)

Bijvoorbeeld: forum-standaardisatie, kennisplatform-apis, vng, common-ground.

Regels

• Maximaal 8 tags totaal per artikel.
• Alle tags moeten voorkomen in tags.yml. Een onbekende tag laat de build falen.

Mappenstructuur

Artikelen staan in docs/ in een van de 7 themacategorieën, elk met subcategorieën per content type:

docs/
├── api-ontwikkeling/
│   ├── standaarden/
│   ├── architectuur/
│   ├── tutorials/
│   └── tools/
├── front-end/
│   ├── standaarden/
│   └── tools/
├── data/
│   ├── standaarden/
│   └── linked-data/
├── security/
│   ├── authenticatie/
│   ├── wetgeving-en-beleid/
│   ├── standaarden/
│   └── tools/
├── devops/
│   ├── standaarden/
│   └── tools/
├── open-source/
│   ├── standaarden/
│   ├── tutorials/
│   └── tools/
└── leidraad/

Plaats je artikel in de map die past bij het thema en het content type. Bijvoorbeeld een tool-artikel over security gaat in docs/security/tools/.

Sectieopbouw per content type

Elk content type heeft een verwachte sectieopbouw (H2-koppen). Je hoeft niet elk kopje te vullen, maar probeer de structuur aan te houden:

Standaard

## Waarom deze standaard
## Wanneer gebruik je dit
## Hoe werkt het
## Toepassing in Nederland
## Bronnen

Tool

## Kenmerken
## Hoe werkt het
## Aan de slag
## Waarom deze tool
## Alternatieven
## Bronnen

Tutorial (single-page)

## Wat je gaat maken
## Vereisten
## Stappen
## Resultaat
## Bronnen

Tutorial (multi-page)

Een multi-page tutorial bestaat uit een index.md met een overzicht en genummerde stap-bestanden (1-eerste-stap.md, 2-tweede-stap.md, etc.).

index.md:

## Wat je gaat maken
## Vereisten
## Stappen
## Bronnen

Architectuur

## Het probleem
## De oplossing
## Kernconcepten
## Wanneer gebruik je dit
## Best practices
## Gerelateerde patronen
## Bronnen

Toon en stijl

Schrijf voor een developer, niet voor een beleidsmaker

De kennisbank richt zich op developers en andere technische profielen die werken aan digitale overheidsdiensten. Schrijf praktisch en concreet: wat moet iemand weten of doen?

Spreek de lezer aan met "je"

Gebruik de informele "je", niet het formele "u". Dit sluit aan bij de toon in ontwikkelaarsdocumentatie en voelt toegankelijker.

Schrijf in het Nederlands, gebruik Engelse termen waar standaard

De kennisbank is Nederlandstalig. Engelse vakbegrippen die in de praktijk zo worden gebruikt — zoals idempotent, pull request, header, of endpoint — hoef je niet te vertalen. Introduceer een acroniem of technische term bij eerste gebruik kort met een uitleg of link.

Wees direct en bondig

Schrijf korte, actieve zinnen. Vermijd ambtelijk taalgebruik, onnodige inleidingen en nominalisaties.

✓ Sla de sleutel op voordat je het verzoek verstuurt.
✗ Het wordt aanbevolen dat de sleutel wordt opgeslagen voorafgaand aan het
versturen van het verzoek.

Gebruik de gebiedende wijs in instructies

Geef instructies als directe opdrachten, niet als suggesties.

✓ Controleer of het gebruik van het bsn is toegestaan.
✗ Je zou kunnen controleren of het gebruik van het bsn is toegestaan.

Geen emoji in koppen of lopende tekst

Emoji horen niet in H2/H3-koppen of in lopende tekst. Ze leiden af en zijn inconsistent met de rest van de kennisbank.

✓ ## Wanneer gebruik je dit
✗ ## 🧠 Wanneer gebruik je dit

Voorbeeld

Hieronder een compleet voorbeeld van een kennisbankartikel:

Voorbeeld: standaard-artikel

---
title: "Security.txt"
content_type: standaard
tags:
  - informatiebeveiliging
---

# Security.txt

Een korte introductie over wat security.txt is.

## Waarom deze standaard

Uitleg over de voordelen en het belang van security.txt.

## Wanneer gebruik je dit

In welke situaties zet je security.txt in.

## Hoe werkt het

Technische uitleg van het formaat en de werking.

## Toepassing in Nederland

Hoe wordt security.txt toegepast bij de Nederlandse overheid.

## Bronnen

- [securitytxt.org](https://securitytxt.org/)