Waarom je documentatie achterloopt op je product

Je hebt een artikel over je instellingenpagina. Drie releases geleden geschreven, en het leest nog altijd goed. Alleen heet de knop in stap vier ondertussen anders en staat die onder een ander tabblad. Niemand heeft dat aangepast. Niemand heeft het ook gemerkt.

Dat is documentation drift: je documentatie loopt achter op je product. Ze is niet fout geworden op één dag. Ze is achtergebleven, één release per keer.

Je documentatie is nooit in één keer verouderd

Verouderde documentatie klinkt als iets dat je overkomt. Alsof er een release was waarna alles fout stond. Zo werkt het zelden.

Elke release verplaatst iets. Een knop verhuist. Een veld krijgt een andere naam. Een stap valt weg omdat het systeem die nu zelf doet. Elk van die wijzigingen is te klein om er de documentatie voor te openen, dus doet niemand dat. Na tien releases beschrijft je artikel een product dat niet meer bestaat, en toch kan je geen enkele release aanwijzen waar het misliep.

Dat is ook waarom bijhouden zo moeilijk is bij een product dat snel verandert. Het probleem zit nooit in één release. Het zit in de optelsom.

Pagina per pagina nalezen werkt niet

De klassieke oplossing: iemand leest alle documentatie na. Elk kwartaal, artikel per artikel, met de laatste versie van het product ernaast.

Dat houdt niemand vol. Bij honderd artikels ben je dagen bezig, en het grootste deel van die tijd lees je artikels die nog perfect kloppen. Het ene artikel dat echt fout staat, zit ergens tussen de negentig andere. Na twee kwartalen schuift het nalezen op naar volgende maand, en daarna naar nooit.

Er is een tweede probleem, en dat is groter. Wie je documentatie naleest, kent je product. Die leest wat er had moeten staan, niet wat er staat. De verplaatste knop in stap vier? Zijn hoofd vult die automatisch in. Hoe beter je je product kent, hoe minder je ziet wat er fout staat.

Je klant kent je product niet. Die volgt stap vier letterlijk, zoekt de knop, vindt die niet, en stuurt een vraag. Je klant leest je documentatie dus wel met de juiste blik. Alleen stuurt hij je geen melding dat het artikel fout is. Hij stuurt een supportvraag.

Laat je klantvragen het werk doen

Daar zit de oplossing. Elke supportvraag over iets dat al gedocumenteerd is, is een melding dat het artikel achterloopt. Ofwel is het onvindbaar, ofwel onduidelijk, ofwel fout. In alle drie de gevallen wijst de vraag je exact aan waar je moet kijken.

Je hoeft dus geen honderd artikels na te lezen. Je moet je klantvragen naast je documentatie leggen. Waar een vraag binnenkomt terwijl het antwoord al bestaat, klopt er iets niet aan dat artikel. Waar een vraag binnenkomt en er bestaat geen artikel, heb je een gat.

Dat kan je met de hand doen, en voor een kleine kennisbank is dat een goed begin. Maar zodra je elke week releaset en elke dag vragen krijgt, wil je een systeem dat die vergelijking voor je maakt. Een systeem dat je klantvragen tegenover je documentatie zet en je de gaten en de fouten aanduidt, zodat jij enkel nog beslist wat er verandert.

Hoe dat bij Sarrai werkt

Sarrai beantwoordt klantvragen op basis van je kennisbank. Bij elk antwoord houdt ze bij hoe zeker ze was. Twijfelt ze, dan gaat de vraag naar een medewerker, die antwoordt zoals altijd.

Daarna vergelijkt Sarrai dat antwoord met het artikel dat ze zelf gebruikt had. Wijkt het af, dan loopt dat artikel achter op je product, en krijg je een voorstel om het bij te werken. Bestond er geen artikel, dan stelt ze voor om er een te maken, met de vraag van de klant als titel en het antwoord van je collega als inhoud.

Het interessantste geval is het artikel waar Sarrai zeker van was, terwijl je medewerker toch iets anders antwoordde. Dat is een artikel dat er compleet uitziet en niet meer klopt. Met nalezen vind je dat nooit. Met een vergelijking wel.

Alle voorstellen komen samen in de goedkeuringsinbox. Je ziet welk gesprek de aanleiding was en wat er zou veranderen. Jij keurt goed, past aan of weigert. Het zoekwerk is gedaan.

Waarom documentatie structureel veroudert en wat je doet als het al een tijd bezig is, lees je in Waarom raakt je documentatie altijd verouderd. Hoe je de signalen uit je klantvragen omzet in een werkritme, staat in Hoe houd ik mijn kennisbank automatisch actueel. Voor softwarebedrijven die wekelijks releasen, is dit de normale gang van zaken.

Wat je maandag kan doen

Neem de laatste twintig supportvragen. Zoek voor elke vraag het artikel dat ze had moeten voorkomen. Bestaat het en klopt het? Dan is het onvindbaar of onduidelijk. Bestaat het en klopt het niet meer? Dan heb je drift gevonden. Bestaat het niet? Dan heb je een gat.

Twintig vragen, een uur werk, en je weet meer over je documentatie dan na een week nalezen.