Documentatie is geen kostenpost. Het is een versneller.

Vraag in een willekeurig ontwikkelteam naar documentatie en de kans is groot dat er iemand diep zucht.

Documentatie heeft niet de beste reputatie. Het kost tijd, loopt achter op de werkelijkheid en wordt volgens sommigen toch nooit gelezen. Tegelijkertijd heb ik nog nooit een organisatie meegemaakt die achteraf vond dat er te veel relevante documentatie was.

Samen met collega Peter Overweel hebben we onlangs een serie afleveringen van Bergler Bytes opgenomen over documentatie. Wat begon als een gesprek over kennisborging en softwareontwikkeling, eindigde uiteindelijk bij een veel actueler onderwerp: AI.

En juist daar zit misschien wel de belangrijkste verandering. Documentatie is niet langer alleen iets voor toekomstige collega’s. Het is steeds meer een directe productiviteitsfactor geworden.

Het misverstand rond documentatie

Veel discussies over documentatie beginnen eigenlijk bij een misverstand. Managers gaan er vaak vanuit dat documentatie er wel zal zijn. Ontwikkelaars gaan er vaak vanuit dat snelheid de hoogste prioriteit heeft. Het gevolg is dat documentatie tussen wal en schip belandt.  Dat lijkt op korte termijn efficiënt. Tot het moment dat een systeem moet worden aangepast, een collega vertrekt of een migratie nodig is. Dan blijkt ineens hoeveel kennis alleen in hoofden en code zit opgeslagen.

We kennen allemaal het begrip technical debt. Maar hetzelfde mechanisme bestaat ook voor documentatie. Je kunt het zien als documentation debt: uitgestelde documentatie die op een later moment alsnog betaald moet worden, vaak tegen een veel hogere prijs.

Code is niet hetzelfde als context

Een veelgehoord argument is dat de code zelf de documentatie is. Daar zit een kern van waarheid in. Code laat zien wat een systeem doet. Maar code vertelt zelden waarom iets op een bepaalde manier gebouwd is. Ze vertelt niets over de afwegingen die onderweg zijn gemaakt, de business rules, architectuurkeuzes of procesafspraken die achter de implementatie zitten.

Dat wordt extra zichtbaar in grotere systemen. Een individuele service kan prima te begrijpen zijn. Maar hoe twintig verschillende modules met elkaar samenwerken, welke events door welke componenten worden verwerkt en hoe een proces door het landschap heen loopt, is vaak niet uit de code af te leiden.

Juist daar ligt de waarde van documentatie.

Goed documenteren gaat niet over meer documenten

Wanneer mensen over documentatie praten, denken ze vaak direct aan dikke Word-documenten die niemand leest.

In de praktijk werkt dat zelden.

Wat wel werkt, is documentatie opnemen in het bestaande ontwikkelproces. Niet als apart project, maar als onderdeel van de normale workflow. Een user story leidt tot een ontwerp, een ontwerp leidt tot implementatie, implementatie leidt tot deployment en uiteindelijk tot gebruik. Op elk van die overdrachtsmomenten ontstaat documentatie.

Dat hoeft niet ingewikkeld te zijn. Templates voor user stories, release notes, deployment guides of incidentrapportages kunnen al veel structuur brengen. De belangrijkste tip daarbij is misschien wel: begin klein. Kies niet direct de perfecte tool of het perfecte proces. Kies iets dat werkt voor jouw team en verbeter het gaandeweg. Net zoals we software ontwikkelen.

Documentatie die niemand leest bestaat niet

Tenminste, meestal niet om de reden die we denken.

Een van de meest gehoorde bezwaren tegen documentatie is dat niemand ernaar kijkt. Maar vaak is de echte oorzaak dat de documentatie simpelweg niet prettig leesbaar is. Een goed document heeft een duidelijke structuur. Het bevat visualisaties waar dat helpt. Diagrammen, praatplaten en eenvoudige illustraties maken informatie makkelijker te begrijpen én beter te onthouden.

Zoals Peter het mooi verwoordde:

“A document that is clear and pleasant to read is a document that will actually be used.”

Dat klinkt misschien triviaal, maar in de praktijk maakt het een enorm verschil.

Waarom AI alles verandert

Het interessante is dat AI het hele gesprek over documentatie op zijn kop zet.

Traditioneel werd documentatie vooral gezien als borging richting de toekomst. Voor nieuwe collega’s, beheerders of toekomstige ontwikkelaars. Dat argument blijft volledig overeind. Maar er is een tweede argument bijgekomen. AI heeft context nodig.

Veel organisaties experimenteren inmiddels met GitHub Copilot, Claude, agentic development en andere vormen van AI-assisted development. Daar zien we telkens hetzelfde patroon terugkomen: hoe beter de context, hoe beter de resultaten.

Ontbreekt die context, dan gaat AI aannames doen.

En daar ontstaat een probleem.

De pindakaasles

Tijdens onze gesprekken gebruikte Peter een mooi voorbeeld.

Een vader vraagt zijn kinderen om uit te leggen hoe hij een boterham met pindakaas moet smeren. De instructies zijn eenvoudig:

“Pak het brood.”

“Doe er pindakaas op.”

“Pak een mes.”

“Smeer de pindakaas uit.”

De vader voert elke instructie letterlijk uit, met hilarische gevolgen. De kinderen ontdekken dat veel kennis die voor hen vanzelfsprekend lijkt, nooit expliciet is gemaakt.

Precies hetzelfde gebeurt bij AI.

Wat niet expliciet wordt vastgelegd, moet worden geïnterpreteerd. En die interpretatie kan goed uitpakken, maar ook volledig verkeerd.

AI wordt steeds beter. Maar context is essentieel.

Context is king

In de praktijk zien we dat AI vooral moeite heeft met zaken die niet letterlijk in de code staan:

• Business rules
• Architectuurkeuzes
• Security-uitgangspunten
• Operationele randvoorwaarden
• Eerdere ontwerpbeslissingen
• Afwijkende organisatieafspraken

Dat zijn precies de dingen die vaak ontbreken in code.

En daarmee komen we bij een opvallende conclusie.

De documentatie die teams jarenlang beschouwden als overhead, blijkt ineens de brandstof voor effectieve AI-ondersteuning.

README-bestanden, architectuurdiagrammen, ontwerpkeuzes en contextdocumentatie helpen niet alleen collega’s om systemen te begrijpen. Ze helpen ook AI om betere voorstellen te doen, betere code te genereren en betere reviews uit te voeren.

Documentatie is niet langer alleen borging

Misschien is dat wel de belangrijkste les uit de hele serie.

Jarenlang werd documentatie vooral verdedigd vanuit risicobeheersing. Voor de dag waarop iemand vertrekt. Voor een audit. Voor een incident. Dat blijft allemaal belangrijk. Maar met de opkomst van AI is er een veel directer argument bijgekomen.

Goede documentatie maakt ontwikkelteams vandaag productiever. Het helpt mensen sneller begrijpen wat ze bouwen. Het helpt AI betere beslissingen nemen. En het helpt organisaties om de voordelen van AI daadwerkelijk te verzilveren. Documentatie is daarmee niet langer alleen een verzekering voor later.

Het wordt steeds meer een versneller voor vandaag.

Conclusie

Als er één boodschap uit deze serie overblijft, dan is het deze:

Documenteer niet alles. Documenteer wat context geeft.

Leg vast waarom keuzes zijn gemaakt. Beschrijf hoe processen samenwerken. Maak architectuur expliciet. Zorg voor een goede introductie voor iemand die morgen voor het eerst naar jouw systeem kijkt.

Niet omdat het moet.

Maar omdat zowel mensen als AI daar beter van worden.