Vernieuwing van de technische documentatie
Status: in voorbereiding, procesvoorstel ligt bij de kring Waar: #gf-cot en #kring-techniek-pub
Wat het is
In verschillende trajecten van het afgelopen jaar is vastgesteld dat de Nuts-documentatie niet toegankelijk is voor nieuwkomers. Daardoor is het moeilijker dan nodig om Nuts te begrijpen of ermee aan de slag te gaan. Het Centraal Ontwikkel Team werkt hieraan vanuit project Generieke Functies en heeft een procesvoorstel gemaakt om de vernieuwing aan te pakken.
De klachten die daaraan ten grondslag liggen:
- De documentatie staat verspreid over verschillende systemen, is daardoor slecht vindbaar en niet in één keer doorzoekbaar.
- Het is onduidelijk welke documentatie voor welk publiek bedoeld is.
- Wiki-documentatie is vaak niet actueel of onaf.
- Er is veel technische documentatie, maar conceptuele documentatie voor algemeen begrip ontbreekt.
- De technische documentatie mist samenhang.
- Documentatie van verschillende versies loopt door elkaar heen.
Relevantie voor Nuts
De documentatie is onderdeel van hoe wij onze standaarden en implementaties beheren en uitdragen, en de omgevingen waarin zij staat vallen onder community-tooling en samenwerkingsmiddelen. De reikwijdte van dit traject omvat naast de knooppunt-documentatie ook de documentatie van de nuts-node en de specificaties, en raakt daarmee ook Beheer en doorontwikkeling nuts-node.
Beoogde uitkomst
Een eenduidige, goed doorzoekbare set documentatie met een duidelijke inhoudsopgave. Tekortkomingen worden opgehaald door met de community te praten; tooling wordt vernieuwd waar nodig, met consent van de huidige eigenaren van die bronnen. Het resultaat wordt getoetst door feedback te vragen aan de verschillende gebruikersgroepen.
Het proces
| Stap | Wat |
|---|---|
| 1 | Inventariseren: welke bronnen zijn er, met welk doel, voor welk publiek, wie schrijft ze en wat is de kwaliteit. En welke persona's willen we bedienen. |
| 2 | Wensen vaststellen: interviews met vertegenwoordigers van stakeholders, aanvullende wensen ophalen en bestaande adviezen verwerken, zoals het rapport van ActiZ en InfoZorg. Resultaat is een doelsituatie met requirements voor inhoud en tooling. |
| 3 | Selectie van documentatie-tooling, op basis van onderzoek naar de opties. |
| 4 | Voorstel tot verbetering: welke bronnen samengevoegd, verwijderd of gearchiveerd, geherstructureerd of uitgebreid moeten worden. |
| 5 | Prototype ontwikkelen, met voorbeelddocumentatie in de gekozen tooling. |
| 6 | Voorstel aan de kring Toepassingen en de kring Techniek: gaan we de documentatie herzien volgens dit prototype? |
| 7 | Realisatie: nieuwe systemen opzetten, content migreren, publiceren, nieuwe documentatie schrijven en de bestaande herstructureren. |
Stap 6 is het besluitmoment. Voordat er iets aan de huidige documentatie verandert, ligt er een inhoudelijk plan bij de kringen. De kringen worden uitgenodigd een afgevaardigde aan het proces te laten deelnemen.
Wat er al ligt
Het document bevat naast het procesvoorstel ook een vooronderzoek en een eerste vernieuwingsvoorstel:
- Referenties. MDN, Dash, Stripe, de RFD's van Oxide, SQLite, Ethereum en Foundry, elk met wat daar goed aan is.
- Doelgroepen. Primair de softwareontwikkelaar, softwarearchitect en DevOps-specialist bij een leverancier, de toepassingsontwerper en de contributor aan de nuts-node. Secundair pentesters, de CTO van een zorgaanbieder en compliance-specialisten. Tertiair beleidsmakers en experts uit andere domeinen.
- Requirements voor de tooling. Onder meer: meerdere bronnen (GitHub-repositories) kunnen combineren, controle houden over de bronnen, OpenAPI-specificaties op een ontwikkelaarsvriendelijke manier kunnen publiceren, een gangbaar formaat zoals markdown, en bij voorkeur zelf te hosten.
- Voorgestelde indeling. Een Nederlandstalige landingsruimte over wat Nuts is en hoe het werkt, plus Engelstalige ruimtes voor de specificaties (v1 en v2) en de nuts-node-documentatie (v5.4, v6.2 en master).
Wat er nu speelt
Het procesvoorstel is op 13 augustus 2026 gedeeld in #kring-techniek-pub en geagendeerd voor de kringvergaderingen van 20 en 27 augustus. Twee commentaarpunten zijn verwerkt. Eén punt is blijven staan: de scope van het traject. De uitkomst van de behandeling is niet vastgelegd in het logboek.
Daarnaast loopt een discussie over twee parallelle sporen en over het ontwikkelen van een prototype.
Te besluiten
- Onderschrijft de kring het procesvoorstel en de reikwijdte daarvan, inclusief de nuts-node-documentatie en de specificaties?
- Vaardigt de kring iemand af naar dit proces?
Samenhang met andere trajecten
- Community-tooling en samenwerkingsmiddelen. De tooling waar de documentatie op draait valt onder die opdracht; een keuze in stap 3 raakt die omgevingen rechtstreeks.
- Beheer en doorontwikkeling nuts-node. De node-documentatie valt binnen de reikwijdte.
- Migratie naar Nuts v6 en did:web. De migratiehandleiding en de deploymentdocumentatie zijn achterstallig en horen bij dit traject thuis.
- Generieke Functies. Het traject loopt vanuit project GF, via het COT.
Bronnen
| Wat | Waar |
|---|---|
| Procesvoorstel Vernieuwing Nuts Documentatie, met vooronderzoek en vernieuwingsvoorstel | Google Docs |
| Aankondiging en verzoek om commentaar, 13 augustus 2026 | Slack, #kring-techniek-pub |
Wie erbij betrokken zijn
| Rol | Wie |
|---|---|
| Procesvoorstel en uitvoering | Rein Krul en Dirk Geurs, namens het COT |
| Afvaardiging vanuit de kring Techniek | nog te bepalen |
| Afvaardiging vanuit de kring Toepassingen | nog te bepalen |
Hoe haak je aan
Heb je last van de huidige documentatie of wil je meedenken over de nieuwe opzet, laat het weten in #gf-cot of in #kring-techniek-aanspreekpunt.