Onlangs gaf ik tijdens de Craftsmanship Day bij Kabisa een presentatie over documentatie. Documentatie wordt vaak gezien als saai en overbodig. Maar in de praktijk is het juist cruciaal: het bepaalt of software ook maanden of jaren later nog te begrijpen en te onderhouden is. Zonder documentatie voelt software al snel als een muur vol hiërogliefen zonder vertaling.
Rosetta Stone
Daarom gebruikte ik de Rosetta Stone als metafoor. In 1799 werd deze steen gevonden in Egypte. Voor het eerst konden wetenschappers hiërogliefen ontcijferen, omdat dezelfde tekst er in drie talen opstond: hiërogliefen, demotisch en Grieks. Zonder die vertaalslag hadden we nooit geweten wat er stond. Documentatie vervult dezelfde rol in onze wereld van softwareontwikkeling: het maakt kennis toegankelijk, ook als de oorspronkelijke bouwers er niet meer zijn.
De prijs van geen documentatie
Ik heb gezien bij bedrijven wat er gebeurt wanneer documentatie niet op orde is. Incidenten die steeds weer terugkomen, omdat niemand het onderliggende probleem goed heeft vastgelegd. Nieuwe collega’s die veel langer doen over hun onboarding. En aannames die uitlopen op dure fouten.
Het voelt als pleisters plakken: het kost tijd en energie, maar lost niets structureel op.
En misschien nog wel belangrijker: documentatie is ook cultuur. Het laat zien dat je rekening houdt met je collega’s. Dat je niet alles alleen in je hoofd wilt houden, maar kennis deelt zodat anderen sneller kunnen werken en minder stress ervaren. Documentatie schrijven is dus óók een sociale daad.
Wat is goede documentatie?
Voor mij is documentatie geen ellenlange wiki die ergens staat te verstoffen. Het leeft mee met de praktijk. Soms in de vorm van een architectuurdiagram, soms een kort Architectural Decision Record waarin we vastleggen waarom we iets zo hebben gebouwd, en soms een Standaard Operating Procedure (SOP) of runbook dat precies beschrijft wat je moet doen als er iets misgaat. Documentatie werkt alleen als het onderdeel wordt van ons normale werk. Als een feature pas “af” is wanneer er ook een stukje uitleg bij zit. Als we documentatie net zo serieus nemen als code. En als we slimme automatisering inzetten om het bij te houden, zodat het geen extra ballast wordt.
De rol van AI
AI gaat daar een enorme rol in spelen (en doet het nu al). Vandaag helpt het al om tekst te schrijven of samen te vatten. Morgen kunnen AI-agents misschien zelfstandig runbooks uitvoeren. Maar AI heeft altijd context nodig. Het kan vaak wel het wat uitvoeren, maar niet het waarom begrijpen. Die context staat in documentatie. Zonder documentatie blijft AI blind.
Onze moderne Rosetta Stone
En dat is misschien wel de belangrijkste boodschap: documentatie is niet alleen voor onszelf, maar ook de brandstof waar AI slimmer van wordt. Zoals de Griekse tekst op de Rosetta Stone ooit de sleutel was tot een hele beschaving, zo kan documentatie nu de sleutel zijn voor duurzame software en AI die ons daadwerkelijk helpt.
Mijn tip? Begin klein. Leg vandaag één keuze vast. Schrijf één SOP. Zorg dat kennis niet alleen in hoofden zit. Voor je het weet, bouw je samen aan een moderne Rosetta Stone.
