Goede documentatie doet één ding boven alles: het helpt lezers te bereiken waarvoor ze gekomen zijn. Het toont niet de kennis van de schrijver, legt niet elk kenmerk in detail uit, en herhaalt de informatie die de lezer al heeft. Het gaat uit de weg.
Tegenwoordig betekent "lezers" meer dan mensen die een pagina scannen. Zoekmachines, AI-antwoordmachines en generatieve AI-assistenten lezen, indexeren en vatten documentatie nu samen voordat een mens deze ziet — vaak beantwoorden ze de vraag namens de mens. Goede documentatie moet voor beide doelgroepen tegelijk werken: de mens die iets voor elkaar wil krijgen, en de systemen die die content onderweg naar boven brengen, rangschikken en citeren.
Dit artikel beschrijft de eigenschappen die documentatie die mensen (en machines) vertrouwen en waar ze naar terugkeren onderscheiden van documentatie die ze achterlaten. Gebruik het als maatstaf bij het schrijven, beoordelen of auditeren van een kennisbank.
De Zeven Kwaliteiten van Goede Documentatie
1. Het is accuraat
Elke stap, screenshot en verklaring weerspiegelt hoe het product zich vandaag de dag daadwerkelijk gedraagt. Onnauwkeurige documentatie is erger dan geen documentatie — het ondermijnt het vertrouwen en kost lezers tijd die ze niet kunnen terugkrijgen. Het vergiftigt ook de bron voor AI-systemen: een AI-assistent die een verouderd artikel citeert, herhaalt de fout vol vertrouwen en op grote schaal, vaak voor meer mensen dan het oorspronkelijke artikel ooit op zichzelf bereikte.
Nauwkeurigheid vereist onderhoud, niet alleen goede bedoelingen op het moment van schrijven. Bouw een beoordelingsproces op dat artikelen markeert wanneer het product verandert. Een artikel dat zes maanden geleden accuraat was, kan vandaag de dag actief misleidend zijn — zowel voor een menselijke lezer als voor elk AI-systeem dat het nog citeert.
2. Het is duidelijk
Duidelijkheid betekent dat een lezer de inhoud bij de eerste keer kan begrijpen, zonder zinnen opnieuw te lezen of definities op te zoeken. Duidelijk schrijven gebruikt korte zinnen, bekende woorden en een logische volgorde. Het gaat er niet van uit dat de lezer weet wat de schrijver weet.
Helderheid helpt ook machines. Zoekmachines, antwoordmachines en taalmodellen analyseren structuur en zinsniveau betekenis om te bepalen wat een artikel daadwerkelijk zegt. Een duidelijk geformuleerd feit is voor een algoritme gemakkelijker te onttrekken en correct te citeren dan een feit dat verborgen zit in een lange, gekwalificeerde zin.
De test voor duidelijkheid is simpel: geef het artikel aan iemand die niet bekend is met het onderwerp en kijk wat hen in de war brengt. Die verwarringspunten zijn je lijst met revisies.
3. Het is compleet
Volledige documentatie dekt alles wat een lezer nodig heeft om de taak te volbrengen — niet meer, niet minder. Het laat geen onverklaarde vereisten achter, slaat geen stappen over die "voor de hand liggen" en stoppen niet zonder duidelijke uitkomst.
Volledigheid betekent niet lengte. Een artikel van 200 woorden dat een vraag volledig beantwoordt, is completer dan een artikel van 2.000 woorden vol zijsporen dat het nooit helemaal beantwoordt. Volledigheid is ook belangrijk voor AI-systemen die een antwoord samenstellen uit je inhoud: een gat in het artikel wordt een gat — of een fabricage — in de reactie van de AI.
4. Het is vindbaar — door mensen en door machines
Documentatie die niet gevonden kan worden, bestaat niet, of de lezer nu iemand is die in een zoekbalk typt of een AI-model dat een bron ophaalt. Findability omvat nu drie overlappende disciplines:
- SEO (Zoekmachineoptimalisatie): Traditionele zoekmachines helpen het artikel te indexeren en te rangschikken, zodat het in de zoekresultaten verschijnt voor de termen die mensen daadwerkelijk gebruiken.
- AEO (Answer Engine Optimalisatie): Content zo structureren dat het direct als een beknopt antwoord kan worden gehaald — in uitgelichte fragmenten, voice-assistant-antwoorden en "quick answer"-vakken. Dit beloont inhoud die het antwoord duidelijk en vroeg formuleert, voordat het wordt toegelicht.
- GEO (Generatieve Engine-optimalisatie): Content eenvoudig maken voor generatieve AI-systemen (chatbots, AI-zoekassistenten, door LLM aangedreven tools) om op te halen, te begrijpen en nauwkeurig te citeren bij het synthetiseren van een antwoord. Dit beloont duidelijke structuur, op zichzelf staande secties, expliciete terminologie en ondubbelzinnige uitspraken die het niet overleven om te worden geparafraseerd.
In de praktijk versterken deze drie disciplines elkaar meer dan dat ze concurreren. Een artikel met een beschrijvende titel, een direct antwoord aan het begin, duidelijke koppen en één duidelijk vermeld feit per sectie presteert doorgaans goed in zoekresultaten, antwoordvakken en AI-citaties.
Denk eerst na over vindbaarheid vanuit het perspectief van de lezer: welke woorden zouden ze gebruiken om dit probleem te beschrijven? Gebruik die woorden — niet interne jargon — in titels en koppen. Controleer vervolgens of de structuur zoekcrawlers, antwoordmachines en AI-modellen even gemakkelijk de juiste informatie kan ophalen.
5. Het is consistent
Consistentie betekent dat lezers je conventies niet van artikel tot artikel opnieuw hoeven te leren. Dezelfde handeling wordt door het hele boek op dezelfde manier beschreven. De koppen volgen hetzelfde patroon. Termen worden elke keer met dezelfde betekenis gebruikt wanneer ze voorkomen.
Inconsistentie is niet alleen een esthetisch probleem. Wanneer dezelfde functie in het ene artikel "dashboard" wordt genoemd en in een ander "startscherm", vragen menselijke lezers zich af of dit twee verschillende dingen zijn — en AI-systemen kunnen oprecht concluderen dat dat zo is, waardoor fouten worden geïntroduceerd in elk antwoord dat op je inhoud is opgebouwd.
6. Het is eerlijk
Goede documentatie erkent beperkingen, bekende problemen en randgevallen. Het overdrijft een kenmerk niet en verbergt geen beperking. Lezers die je documentatie vertrouwen komen terug; Lezers die zich erdoor misleid voelen, doen dat niet.
Als iets niet in alle situaties werkt, zeg het dan. Als er een workaround bestaat, bied die dan aan. Eerlijke documentatie bouwt het soort vertrouwen op dat geen enkele marketing kan creëren — en het is ook wat AI-systemen ervan weerhoudt om een overgeblazen bewering vol vertrouwen als feit te herhalen.
7. Het is gestructureerd voor machineconsumptie
Dit is de nieuwste vereiste en vervangt de zes bovenstaande kwaliteiten niet — het hangt ervan af. Structuur is wat ervoor zorgt dat nauwkeurigheid, helderheid en volledigheid daadwerkelijk de lezer bereiken, menselijk of anderszins.
Goed gestructureerde documentatie gebruikt beschrijvende koppen, één idee per sectie, korte alinea's en expliciete in plaats van impliciete relaties tussen ideeën (bijvoorbeeld het benoemen van de functie in plaats van te vertrouwen op "dit" of "het" over alinea-onderbrekingen). Dit soort structuur helpt een menselijke lezer de pagina te scannen, en het helpt een zoekcrawler, antwoordmachine of taalmodel om een feit correct toe te wijzen aan de juiste context in plaats van het samen te voegen met een naburige context.
Structuur is geen vervanging voor inhoud. Een artikel dat prachtig is opgemaakt maar onnauwkeurig of onvolledig zal de lezer nog steeds teleurstellen — het zal alleen sneller falen en breder worden geciteerd tijdens het proces.
Wat goede documentatie niet is
Het is de moeite waard om even duidelijk te zijn over wat goede documentatie voorkomt.
- Het is geen lijst met functies. Het opsommen van alles wat een product kan is een marketingoefening, geen documentatietaak. Documentatie legt uit hoe je specifieke doelen bereikt, niet hoe indrukwekkend het product is.
- Het is geen transcript van de UI. Als elk artikel simpelweg herhaalt wat al zichtbaar op het scherm staat, voegt de documentatie geen waarde toe. Leg uit wat je moet doen en waarom, niet alleen wat er bestaat.
- Het is niet permanent. Documentatie die niet wordt beoordeeld en bijgewerkt, wordt een risico. Behandel elk artikel als een levend document met een houdbaarheid.
- Het is niet geschreven voor de schrijver. Documentatie is een product dat gericht is op de lezer. De voorkeuren, expertise en aannames van de schrijver zijn niet relevant. Wat telt is wat de lezer nodig heeft.
- Het is niet alleen geschreven voor trefwoorden. Optimaliseren voor zoektermen ten koste van duidelijkheid levert content op die rankt maar niet helpt — en AI-systemen worden steeds beter in het detecteren en negeren ervan. Optimaliseer voor de lezer; De ranglijst volgt.
Een praktische maatstaf
Stel voordat je een artikel publiceert, deze vragen:
- Kan een lezer deze taak volbrengen nadat hij dit heeft gelezen, zonder iemand om hulp te vragen?
- Is elke uitspraak in dit artikel vandaag de dag waar?
- Zou een lezer zonder achtergrondkennis dit begrijpen?
- Als een lezer naar dit onderwerp zou zoeken, zou hij dit artikel vinden?
- Als een AI-assistent dit artikel zou samenvatten, zou de samenvatting dan accuraat en compleet zijn?
Als het antwoord op een van deze vragen nee is, is het artikel nog niet klaar.