Hoe je je documentatie in sync houdt met een product dat wekelijks verandert

Wekelijks uitrollen is goed voor je product en zwaar voor je documentatie. Elke release is een kleine verandering aan de werkelijkheid, en elke kleine verandering is een kans voor een artikel om achterop te raken. De artikels verouderen niet in één keer. Ze schuiven weg, één verplaatste knop tegelijk, tot een klant een stap volgt die niet meer bestaat en je er op de harde manier achter komt.

Je kan het product niet bevriezen om de docs te beschermen, en dat zou je ook niet willen. Wat je wel kan doen, is een werkwijze bouwen waarin je documentatie actueel houden een kleine, regelmatige gewoonte wordt. Het is dan niet langer de driemaandelijkse opkuis die er nooit echt van komt. De vier praktijken hieronder laten zien hoe dat eruitziet in een team dat vaak uitrolt.

Koppel elke wijziging aan een documentatiecontrole

Documentatie veroudert wanneer het schrijven ervan los staat van het bouwen van wat het beschrijft. De oplossing is om één vraag, "verandert dit iets aan de docs?", vast te haken aan het moment waarop de wijziging gebeurt, zodat ze beantwoord wordt terwijl de context nog vers in iemands hoofd zit.

Je hebt al natuurlijke controlepunten waar een wijziging echt wordt. Haak de documentatievraag aan één daarvan:

• De pull request. Een kort checklist-item, "docs bijgewerkt of niet nodig", dwingt een ja of nee af voor de merge. Het kost de auteur tien seconden en vangt de wijziging op het moment dat hij ze het best begrijpt.
• De release notes. Als een regel de moeite waard is om aan klanten te vertellen, is hij de moeite waard om te checken of een artikel moet meebewegen. Loop de changelog af en stel de vraag voor elke regel.
• Het ticket dat bijna sluit. Een functie is af wanneer iemand buiten het team kan uitzoeken hoe hij werkt, dus de doc-check hoort op hetzelfde ticket als de code.

Niets hiervan vereist een tool, alleen een gewoonte en een plek om het antwoord vast te leggen. De beslissing over de docs hoort waar de kennis zit: op het moment van de wijziging, bij de persoon die je nog precies kan vertellen wat er verschoof en waarom.

Houd elke aanpassing klein genoeg om ze echt te doen

Docs raken ook achterop omdat ze bijwerken als een karwei voelt. Als elke aanpassing betekent dat je een muur van tekst openslaat, het hele artikel herleest en drie alinea's herschrijft om consistent te blijven, stellen mensen het uit. Genoeg kleine uitstellen samen worden een backlog die niemand nog wil aanraken.

Verlaag de kost van een enkele aanpassing. Schrijf artikels in kleine, op zichzelf staande stukken, zodat een wijziging één alinea raakt en de rest met rust laat. Een correctie van twee regels die je vandaag doet, is beter dan een volledige herschrijving die je blijft uitstellen. Een set docs die iets ruw maar actueel is, is nuttiger dan een gepolijste die het product van vorig kwartaal beschrijft.

Laat de vragen die je krijgt je backlog schrijven

Je hoeft niet te raden welke artikels zijn weggeschoven. Je klanten vertellen het je elke dag, in de vragen die ze stellen. Een vraag die je team of je AI-assistent niet goed kon beantwoorden, wijst rechtstreeks naar een gat: ofwel ontbreekt het artikel, ofwel staat het er en klopt het niet.

Behandel elke onbeantwoorde of slecht beantwoorde vraag als een documentatietaak. Dat draait de gebruikelijke volgorde om: je klanten bepalen de prioriteiten, en de gaten die ze het vaakst raken komen vanzelf bovendrijven. Zo wordt de backlog een concrete lijst van echte gaten, gerangschikt naar hoe vaak ze opduiken, en weet je meteen waar je moet beginnen.

Maak van schrijven vanaf nul een snelle review

Documentatie schrijven vanaf een blanco pagina is het traagste en minst geliefde werk in het team. Een voorgestelde wijziging nakijken gaat snel, en de meeste mensen doen dat graag. Maak van "schrijf dit artikel" een "keur deze voorgestelde aanpassing goed, pas ze aan, of wijs ze af", en het meeste ongemak verdwijnt.

Dat is het idee achter Sarrai's goedkeuringsinbox. Wanneer een vraag een gat blootlegt, schrijft Sarrai het artikel of de aanpassing en zet het in een wachtrij. Jij doet het deel dat alleen een mens hoort te doen: nagaan of het klopt, de formulering bijschaven, goedkeuren. Het opzoekwerk en de eerste versie zijn al gebeurd, dus je docs actueel houden wordt een kwestie van een inbox leegmaken. De namiddag die je vroeger voor schrijven blokkeerde, komt terug op je agenda.

Of een tool de wijziging nu opstelt of een collega, het principe is hetzelfde: vanaf nul schrijven hoort zeldzaam te zijn, nakijken hoort routine te zijn. Die verhouding maakt wekelijks onderhoud haalbaar.

In sync blijven is een gewoonte

Docs in sync houden met een snel bewegend product komt neer op een handvol kleine gewoontes. Beslis over de docs op het moment dat je het product wijzigt. Houd elke aanpassing goedkoop. Volg de echte vragen die je klanten stellen. Kijk een kant-en-klare versie na wanneer dat kan. Doe die vier dingen en het gat tussen je product en je documentatie blijft klein, te meten in dagen.

Wil je de langere versie van waarom documentatie überhaupt wegschuift, en waarom dashboards die het probleem alleen rapporteren het nooit dichten, dan schreven we daarover in waarom je documentatie altijd verouderd raakt.