Documenteren

Goede documentatie heeft een positieve invloed op de uiteindelijke kwaliteit van software, en zorgt er ook voor dat het onderhoud van software beter kan worden uitgevoerd. Goede documentatie is ook van levensbelang bij taak- of personeelswijzigingen in een bedrijf. In de praktijk heeft onduidelijke documentatie dan ook bij veel organisaties voor grote problemen gezorgd. Jij gaat daarom duidelijk documenteren.

Je gaat schrijven in een stijl die past bij documentatie. Documentatie is een vorm van technisch schrijven, en daarom ga je actief schrijven als belangrijk middel om ambiguïteit te voorkomen. Verder ga je teksten goed structureren zodat elke lezer de gedachte achter jouw ontwerp, product of software goed kan volgen. Dat betekent dat je schrijft in korte alinea’s met koppen. Spelling en grammaticafouten leiden af en kunnen ook tot onduidelijkheid leiden; je schrijft daarom ook foutloos. Je schrijft semi-formeel omdat te joviaal of te formeel taalgebruik ook kan leiden tot miscommunicatie.

Verplaats je in de doelgroep

Denk goed na voor wie je de documentatie schrijft, een eindgebruiker heeft niets aan een diep technisch document maar veel meer aan een stap-voor-stap handleiding. Verplaats je zoveel mogelijk in je doelgroep zodat je de documentatie hiervoor op maat kunt schrijven.

Geef een duidelijke inleiding

Vermeld altijd een stukje informatie over het document wat je schrijft. Hierin kun je bijvoorbeeld de datum en versie nummer van het document in zetten. Maar ook wijzigingen nadat je delen uit de documentatie hebt aangepast door vernieuwingen.

Let op taal

Gebruik geen werkwoorden in de lijdende vorm. Dus “Druk de schakelaar in” en niet “De schakelaar moet worden ingedrukt”. Vaak gaat dit vanzelf als je duidelijk benoemt wie of wat voor iets verantwoordelijk is, zoals hier: “De eindgebruiker update wekelijks de klantgegevens”, ipv “De klantgegevens worden wekelijks geüpdatet.”

• Gebruik de tegenwoordige tijd en voorkom hulpwerkwoorden als “zullen”. Dus niet “Druk de schakelaar in. Een lichtje zal gaan branden” maar “Druk de schakelaar in en een lichtje gaat branden“.
• Gebruik relatief korte zinnen. Een zin met meer dan 10 woorden is al te lang. De voorgaande zin heeft 10 woorden, precies goed!
• Beperk technisch jargon tot een minimum. Wees bij technische termen die u wél gebruikt consequent. Je kan hier bijvoorbeeld “knop” gebruiken als synoniem voor “schakelaar”. Denk goed na over welke van de twee termen de doelgroep het eenvoudigst begrijpt.
• Voorkom het gebruik van afkortingen enerzijds, en van lange, samengestelde woorden anderzijds.
• Probeer uitdrukkingen en zegswijzen te voorkomen.
• Gebruik witregels. Probeer niet te veel informatie op één pagina te proppen.
• Gebruik lijsten en opsommingen, zoals deze.
• Voeg tabellen, diagrammen en afbeeldingen in, maar alleen als ze een duidelijke toegevoegde waarde hebben.

Oefening

Schrijf documentatie en vraag hierover feedback aan de taaldocenten.