Documentatie heeft een levenscyclus. Het wordt gecreëerd om aan een behoefte te voldoen, wordt gehandhaafd om accuraat te blijven naarmate dingen veranderen, en uiteindelijk met pensioen gestuurd wanneer die behoefte niet meer bestaat. Documentatie behandelen als iets dat één keer geschreven is en dan met rust wordt gelaten, is de meest betrouwbare weg naar een kennisbank die lezers — en steeds meer de AI-systemen die namens hen antwoorden — niet meer vertrouwen.
Dit artikel beschrijft elke fase van de documentatielevenscyclus en de praktijken die een kennisbasis in de loop van de tijd gezond houden.
Fase 1: Creëer
Creatie begint niet wanneer je een leeg document opent, maar wanneer je een behoefte identificeert. Er bestaat een documentatiebehoefte wanneer lezers een doel niet kunnen bereiken zonder hulp — en die hulp bestaat nog niet in je kennisbasis.
Identificeer wat er geschreven moet worden
De meest betrouwbare signalen voor documentatiegaten zijn supportverzoeken, gebruikersfeedback en zoekopdrachten die geen resultaten opleveren. Als je supportteam tien keer per week dezelfde vraag beantwoordt, heeft die vraag een artikel nodig. Als lezers zoeken naar een term die niet in je kennisbank voorkomt, moet die term er zijn.
Behandel je supportwachtrij als een documentatiebacklog. Elke vraag die met documentatie beantwoord had moeten worden — maar dat niet was — is een leegte om te dichten.
Schrijf met een gedefinieerde scope
Definieer voordat je schrijft precies wat het artikel wel en niet zal behandelen. Een gedefinieerde scope voorkomt dat artikelen oneindig uitbreiden en houdt ze gericht op één lezersdoel. Schrijf de scope in één zin op voordat je begint: "Dit artikel legt uit hoe je [opdracht] moet doen voor [publiek], beginnend bij [vereiste toestand]."
Als je die zin niet duidelijk kunt schrijven, heb je nog niet genoeg duidelijkheid over wat je schrijft. Verduidelijkt eerst de scope.
Recensie vóór publicatie
Elk artikel moet door minstens één andere persoon worden beoordeeld voordat het wordt gepubliceerd — bij voorkeur iemand met inhoudelijke expertise die de juistheid kan controleren, en iemand die niet bekend is met het onderwerp en duidelijkheid kan controleren. Deze twee beoordelaars ontdekken verschillende soorten problemen. Eén persoon die zowel expert is als onbekend is met het perspectief van de lezer, is geen vervanging voor beide.
Fase 2: Onderhouden
Onderhoud is de fase die de meeste kennisbases verwaarlozen en het meest onder lijden. Een niet onderhouden kennisbank blijft niet neutraal — hij verslechtert actief. Onnauwkeurige artikelen worden gelezen en opgevolgd. Verouderde stappen sturen lezers de verkeerde kant op. Termen die niet meer betekenen wat ze ooit betekenden, creëren verwarring.
Dit risico is niet langer beperkt tot menselijke lezers. Een AI-assistent die een verouderd artikel citeert, kan verouderde of verkeerde informatie naar voren brengen bij iemand die dat artikel nooit via zoeken of navigeren zelf zou hebben gevonden — vaak met hetzelfde vertrouwen gepresenteerd als accurate inhoud. Een niet onderhouden kennisbasis verliest niet zomaar stilletjes het vertrouwen van lezers die op oude artikelen stuiten; Het kan fouten actief verspreiden door elk systeem dat deze ophaalt en samenvat.
Stel een beoordelingsschema op gebaseerd op twee variabelen, niet één
Wijs aan elk artikel een beoordelingsdatum. Het juiste interval hangt af van twee dingen die samenwerken, niet slechts één:
- Hoe vaak de onderliggende inhoud verandert. Artikelen over snel veranderende functies moeten mogelijk elk kwartaal worden herzien; Fundamentele conceptuele artikelen hoeven mogelijk alleen jaarlijks te worden beoordeeld.
- Inhoudstype. Een referentieartikel (zoals een API of parameterlijst) raakt vaak verouderd zodra een onderliggend systeem verandert en moet in hetzelfde tempo worden beoordeeld als de releasecyclus van dat systeem. Een conceptueel artikel dat een stabiel mentaal model uitlegt, kan gerust langer doorgaan tussen de beoordelingen. Een probleemoplossingsartikel moet opnieuw worden bekeken zodra het beschrijft symptoom van vorm verandert — zelfs als de onderliggende eigenschap op papier niet is veranderd.
Stel reviewherinneringen in in je workflowsysteem. Wanneer een beoordelingsdatum aanbreekt, controleert de artikelhouder of de inhoud nog steeds accuraat is en werkt deze bij als dat niet zo is. Als het klopt, zetten ze de beoordelingsdatum opnieuw en gaan ze verder. Dit kost minuten voor een artikel dat niet is veranderd en alleen uren wanneer er belangrijke updates nodig zijn.
Koppel documentatie aan productwijzigingen
De meest betrouwbare manier om ervoor te zorgen dat documentatie actueel blijft, is door documentatie-updates onderdeel te maken van het productreleaseproces, niet als bijzaak. Wanneer een functie verandert, verandert de documentatie van die functie tegelijkertijd — niet weken later als iemand het verschil opmerkt.
Dit vereist een relatie tussen het documentatieteam en degene die de productreleases beheert. Het proces hoeft niet complex te zijn: een gedeeld checklistitem met de tekst "documentatie bijgewerkt" voordat een release wordt verzonden, is voldoende.
Reageer op feedback
Lezersfeedback — of het nu via beoordelingen, opmerkingen of supporttickets is uw meest directe signaal dat een artikel aandacht nodig heeft. Een artikel dat consequent slechte beoordelingen krijgt of vervolgvragen oproept, vertelt je iets. Onderzoek het.
Let ook op signalen die verder gaan dan directe feedback: een stijgend aantal zoekopdrachten die op een artikel terechtkomen maar direct gevolgd worden door een herhaalde zoekopdracht (wat suggereert dat het artikel de vraag niet beantwoordde), of een merkbare verandering in hoe vaak een AI-assistent of zoekmachine het artikel citeert, kunnen beide wijzen op een kwaliteitsprobleem voordat een enkele lezer klaagt.
Wacht niet tot feedback zich verzamelt. Een enkele lezersreactie die zegt "stap 4 werkt niet" is genoeg om een beoordeling te triggeren.
Laat de lezers zien dat het artikel wordt onderhouden
Een zichtbare "laatst bijgewerkte" datum, en — voor belangrijke wijzigingen — een korte notitie over wat er is veranderd, bouwt het vertrouwen van de lezer op op een manier op die een onzichtbaar onderhouden artikel niet kan. Lezers (en recensenten) zijn eerder geneigd een artikel te vertrouwen dat zichtbaar bewijs van verzorging toont dan een artikel dat geen enkel signaal geeft.
Fase 3: Met pensioen gaan (of consolideren)
Documentatiepensioen is het minst geoefende deel van de levenscyclus, maar het is net zo belangrijk als creatie en onderhoud. Een artikel over een verouderde functie, een proces dat niet meer bestaat, of een productversie die niet meer wordt ondersteund, is niet neutraal — het is misleidend. Lezers die het vinden en volgen, zullen problemen of fouten tegenkomen en het vertrouwen in je documentatie als geheel verliezen. Erger nog, een AI-systeem dat zich niet bewust is dat het artikel verouderd is, kan het voor onbepaalde tijd als actueel feit aanhalen.
Identificeer kandidaten voor pensioen
Een artikel is een kandidaat voor pensioen wanneer:
- De functie of het proces dat het beschrijft, bestaat niet meer.
- Het is vervangen door een nieuwer artikel dat hetzelfde onderwerp nauwkeuriger behandelt.
- De productversie waarop het van toepassing is, wordt niet langer ondersteund.
- Het krijgt consequent lage beoordelingen en het onderliggende onderwerp is niet langer van toepassing.
- Uit analyses blijkt dat het bijna geen verkeer krijgt en dat het onderwerp niet iets is wat lezers nodig hebben.
Weet wanneer je moet consolideren in plaats van met pensioen gaan
Niet elk probleemartikel moet volledig worden afgebroken. Een veelvoorkomend scenario zijn twee artikelen die hetzelfde onderwerp behandelen — vaak geschreven door verschillende mensen op verschillende momenten — zonder dat een van beide ongelijk heeft. Wanneer dit gebeurt, is de juiste stap meestal om ze samen te voegen tot één gezaghebbend artikel in plaats van het ene te verwijderen en het andere te behouden, omdat het overgebleven artikel zelf onvolledig kan zijn. Meng de juiste inhoud van beide, stuur de verliezer met pensioen met een doorverwijzing naar het samengevoegde resultaat, en noteer de consolidatie in de updategeschiedenis van het overgebleven artikel.
Ga met gracieuze pensioen
Het terugtrekken van een artikel betekent niet altijd dat het onmiddellijk wordt verwijderd. Als het artikel nog relevant is voor lezers van oudere versies, archiveer het dan met een duidelijke mededeling bovenaan waarin wordt uitgelegd dat de inhoud alleen op een specifieke versie van toepassing is en met een link naar de huidige documentatie.
Als het artikel echt verouderd is, verwijder het dan — en maak een redirect van de URL naar het meest relevante huidige artikel. Een lezer die een gepensioneerd artikel heeft gebookmarkt, zou ergens nuttig moeten terechtkomen, niet op een 404-fout. Een doorleiding voorkomt ook dat een zoekmachine of AI-systeem nog lang na het verdwijnen van het artikel een dode link blijft zien.
Eigendom en verantwoording
Een documentatielevenscyclus werkt alleen als iemand er verantwoordelijk voor is. Elk artikel zou een eigenaar moeten hebben — iemand die verantwoordelijk is voor de nauwkeurigheid en actualiteit ervan. In een klein team kan één persoon alles bezitten. In een groter team wordt het eigendom meestal verdeeld per onderwerpgebied of productfeature.
Documenteer het eigendom duidelijk en houd het actueel. Wanneer het eigendom verandert — omdat iemand het team verlaat of de verantwoordelijkheid voor een productgebied verschuift — werk tegelijkertijd de eigendomsrecords bij de documentatie. Niet-eigendom documentatie wordt verouderde documentatie.
Plan voor de onderbreking, niet alleen voor de toewijzing: wanneer de eigenaar van een artikel vertrekt of vertrekt en er nog geen opvolger is benoemd, zou het eigenaarschap automatisch moeten kiezen voor een aangewezen vangnet — meestal de teamleider of de eigenaar van de hoofdcategorie — in plaats van ontoegewezen te blijven zitten totdat iemand het opmerkt. Een artikel zonder eigenaar, zelfs tijdelijk, is een artikel dat niet wordt beoordeeld.