Hoe schrijf je technische documentatie

Kies één taak, één lezer en één bron van waarheid. Schrijf daarna de stappen in gewone taal, test ze met iemand die ze niet heeft geschreven, en schrap alles wat de lezer niet helpt de klus af te maken.

Voordat je begint

Goede technische documentatie begint al vóór de eerste zin. Kies eerst één taak. Schrijf bijvoorbeeld over 'een nieuwe payment gateway koppelen', niet over 'de app documenteren'. Dat geeft je een duidelijke eindstreep en houdt de pagina nuttig.

Kies daarna de lezer. Een ontwikkelaar heeft setupnotities, commando's en uitzonderingsgevallen nodig. Een supportmedewerker heeft symptomen, controles en oplossingen nodig. Een projectleider heeft misschien status, afhankelijkheden en overdrachtsnotities nodig. Eén pagina kan één van die drie goed bedienen, of op alle drie tekortschieten.

Verzamel dan de bron van waarheid. Dat kan code zijn, tickets, screenshots, ontwerpnotities, logs, een runbook of een oude handleiding die nog één goede sectie heeft. Als twee bronnen elkaar tegenspreken, stop dan en vraag welke leidend is voordat je begint met schrijven.

Kies het format voordat je begint te schrijven. Een installatiegids, een naslagpagina en een storingspagina hebben elk een andere opzet nodig. Voor een controller van een zit-sta-bureau kan een installatiegids koppelen en kalibreren uitleggen. Een naslagpagina kan knoppen en lichtbetekenissen noemen. Een storingspagina kan een vastzittende lift of een knipperend foutlampje behandelen.

Hoe technische documentatie schrijven

• Schrijf eerst het resultaat. Zeg wat de lezer kan doen nadat de pagina werkt. Voorbeeld: 'Aan het einde heb je de staging-app gekoppeld aan Stripe.'
• Gebruik een simpele volgorde: doel, wat je nodig hebt, stappen, resultaat, oplossingen. Zo blijft de lezer in beweging.
• Schrijf per stap één actie. 'Open de admin-console. Selecteer Facturering. Kies Betaalmethode toevoegen.' Dat is makkelijker te volgen dan een lange alinea met vijf werkwoorden.
• Gebruik exacte namen voor knoppen, velden, mappen, commando's, foutcodes en bestandsnamen. Als het scherm Betaalmethode toevoegen zegt, noem het in de documentatie dan niet Nieuwe kaart.
• Houd termen gelijk. Als je in stap 1 workspace zegt, stap dan in stap 4 niet over naar projectgebied.
• Zet het waarschijnlijke probleem naast de stap die het veroorzaakt. Als toegang vaak het probleem is, zeg dat daar. Voorbeeld: 'Als de knop ontbreekt, controleer dan of je Billing Admin-toegang hebt.'
• Gebruik kopieerbare voorbeelden voor software en code. Laat eerst het commando zien, en daarna direct het verwachte resultaat. Zo kan de lezer snel zijn eigen scherm controleren.
• Schrijf korte alinea's. Eén idee per alinea is genoeg. Heeft een alinea te veel ideeën, splits hem dan op in twee.
• Haal alles weg wat iemand niet helpt om de taak af te maken. Achtergrond is alleen nuttig als het een fout voorkomt.
• Voeg aan het einde de volgende stap toe. Link bijvoorbeeld naar de testpagina, de storingspagina of het volgende deel van de setup.

Een simpele stapopmaak

Een vaste opmaak voor stappen houdt documentatie leesbaar als de taak ingewikkeld wordt. Gebruik voor elke stap deze opzet: actie, resultaat, oplossing als dat nodig is. Dat werkt voor software-installatie, overdrachten binnen een project en workflows op basis van commando's.

Voorbeeld voor een ontwikkelaarspagina: 'Voer npm install uit. Je zou moeten zien dat de pakketlijst wordt bijgewerkt. Als het mislukt, controleer dan of Node 20 is geïnstalleerd.' Zo geef je de lezer iets om te doen, iets om te verwachten en iets om te controleren.

Voor: 'Los daarna het afhankelijkheidsprobleem op.' Na: 'Voer npm install uit. Als je een machtigingsfout ziet, open de terminal dan opnieuw als gebruiker met schrijfrechten.' De tweede versie kost meer tijd om te schrijven en is sneller te gebruiken.

Voor een pagina over een controller van een zit-sta-bureau kun je schrijven: 'Houd de knoppen omhoog en omlaag drie seconden ingedrukt. Het display zou één keer moeten knipperen. Gebeurt dat niet, haal de controller dan uit het stopcontact en probeer het opnieuw.' Dat is duidelijk, testbaar en specifiek.

Wat goede technische documentatie bevat

Een nuttige pagina volgt meestal deze volgorde: titel, korte opening, vereisten, stappen, verwachte resultaten, oplossingen, volgende stap. Die volgorde werkt omdat je daarmee de vragen van de lezer in dezelfde volgorde beantwoordt als waarin ze opkomen.

De titel moet de taak noemen. De opening moet de lezer vertellen voor wie de pagina is en wat hij behandelt. De vereisten moeten alleen noemen wat vooruitgang blokkeert, zoals een account, een kabel, een versie of een login.

De stappen moeten in de echte volgorde staan, niet in de volgorde die slim klinkt. Zet waarschuwingen alleen neer waar ze ertoe doen. Voeg een korte sectie met oplossingen toe voor de meest voorkomende missers. Eindig met een duidelijk stopmoment, zoals een testrun of een overdracht.

Voor een pagina over het instellen van een payment gateway kan dat er zo uitzien: 'Koppel Stripe aan de test-app. Je hebt admin-toegang en een testsleutel nodig. Volg de stappen om de sleutel te plakken, de instelling op te slaan en een testbetaling uit te voeren. Als de test mislukt, controleer dan de sleutel en de accountrechten. Ga daarna naar de pagina voor webhookinstellingen.'

Test het voordat je publiceert

Vertrouw de conceptversie niet alleen omdat hij voor jou goed leest. Geef hem aan iemand die hem niet heeft geschreven. Vraag die persoon om hem zonder hulp te volgen. Kijk waar die persoon pauzeert, gokt of teruggaat.

Als die persoon pauzeert, mist de pagina misschien een vereiste of een kleine installatiestap. Voeg die stap toe dicht bij de eerste plek waar hij nodig is.

Als die persoon gokt, is de formulering vaag. Vervang 'voer de juiste waarde in' door de exacte veldnaam, het label of het bestandspad.

Als die persoon teruggaat, klopt de volgorde niet. Zet de stap eerder, of splits de pagina op zodat de lezer niet hoeft te springen.

Probeer het verwarrende deel op te lossen, niet alleen de zin eromheen. Soms is de echte oplossing een nieuwe vereiste, een andere screenshot of een tweede pagina.

Voor een snelle check kun je tools manual check doorlopen. Als je dezelfde gewoonte nodig hebt voor fysieke instructies, vergelijk dan de structuur met this guide.

Wat meestal misgaat

Het meest voorkomende probleem is te veel context en te weinig actie. Lezers hebben vóór de knopnaam geen geschiedenisles nodig.

Een andere misser is meerdere taken op één pagina mengen. Installatie, troubleshooting en naslag vechten dan om ruimte. Splits ze op wanneer de lezer van denkmodus moet wisselen.

Screenshots verouderen snel. Gebruik ze alleen voor schermen die weinig veranderen. Als labels vaak verschuiven, gebruik dan liever een korte callout of een bijgesneden afbeelding in plaats van een volledige schermafbeelding.

Vage woorden zorgen ook voor problemen. Laat 'simpel', 'makkelijk' en 'gewoon' weg. Ze lossen geen vastgelopen deployment of ontbrekende machtiging op.

Als een pagina te vol lijkt, haal dan eerst de extra’s weg. Houd de stappen over die de lezer naar een werkend resultaat brengen.

Hoe lang het duurt

Een korte how-to-pagina kan 30 tot 60 minuten kosten als de bron schoon is en de taak simpel.

Een normale handleiding voor software-installatie duurt meestal 2 tot 4 uur, als je het uitwerken, controleren van de stappen en bewerken meerekent.

Een groter project met uitzonderingen, screenshots en reviewrondes kan een groot deel van een dag kosten.

Het trage deel is meestal bewijzen dat de stappen werken, niet het typen zelf. Als het proces rommelig is, schrijf je documentatie terwijl je de taak doet. Dan zie je snel welke kliks ontbreken, welke aannames verborgen zijn en welke formuleringen lastig zijn.

Wanneer een videoversie helpt

Een geschreven pagina blijft de beste plek voor zoeken, naslag en tekst die je precies kunt kopiëren. Een video helpt als de taak veel stappen heeft, schermen vaak veranderen of support dezelfde vraag steeds opnieuw krijgt. Dat komt vaak voor bij onboarding, setup en praktische procedures.

Als je al een montagehandleiding of instructiepagina hebt, kan een korte gefilmde versie ernaast staan. Manual to Video zet een bestaande handleiding om in een geanimeerde, ondertitelde stap-voor-stapfilm in jouw merkkleuren en met jouw logo. Het werkt ook met een QR-code op de handleiding, de doos, een productpagina of een supportartikel.