Zorg met heldere documentatie voor betere code
Bij software zijn niet alleen handleidingen voor gebruikers nodig, maar ook documentatie voor de ontwikkelaars. Goede documentatie voor ontwikkelaars is essentieel voor efficiënte samenwerking tussen ontwikkelaars en resulteert uiteindelijk in betere en consistentere code. In sommige gevallen maakt de documentatie deel uit van een volledige software development kit, waarmee externe ontwikkelaars zelfstandig aan de slag kunnen. Maar ook op kleinere schaal kan heldere documentatie een groot verschil maken.
Ga verder dan een ‘README.txt’-bestand: soorten softwaredocumentatie
Bij het opstellen van softwaredocumentatie is het belangrijk om eerst goed in kaart te brengen welke informatie nodig is bij de verschillende taken binnen een softwareontwikkelingsteam. In veel gevallen is de documentatie niet tegelijkertijd met de software mee ontwikkeld, en moet een inhaalslag gebeuren op het vlak van documentatie. Het gaat dan al snel om een grote hoeveelheid informatie, die op een bruikbare manier uitgewerkt moet worden.
Gelukkig moet het wiel niet telkens opnieuw uitgevonden worden. Bewust of onbewust werken ontwikkelaars continu met softwaredocumentatie die online beschikbaar is. Dit kunnen we benutten, door dezelfde specifieke soorten technische documentatie aan te bieden, met een vaste en herkenbare structuur, zoals bijvoorbeeld:
API-documentatie
datamodeldocumentatie
architectuurdocumentatie
referentiepagina’s voor functies, events, objecten, etc.
UX-designsysteem
Schrijf en beheer ‘docs-as-code’
We volgen graag de aanpak van 'docs-as-code'. Dit wil zeggen dat we de documentatie schrijven en beheren op dezelfde manier en met dezelfde tools als de code. Meestal kiezen we ervoor om de documentatie te schrijven in Markdown omdat softwareontwikkelaars hier al vertrouwd mee zijn, maar dit kan ook met DITA of een combinatie van beide. Indien de bestanden steeds in de repository van de beschreven code worden geplaatst, kunnen ze ook gemakkelijk worden teruggevonden en onderhouden.
Markdown en DITA kunnen eenvoudig worden geconverteerd naar HTML om de content te publiceren op een portaal. Wij maken hiervoor graag gebruik van een “static site generator” (zoals Eleventy of MkDocs). Die aanpak heeft als voordeel dat er direct diverse plug-ins beschikbaar zijn om de Markdown te verrijken met onder andere (klikbare) diagrammen, code snippets, zoek- en navigatie-functionaliteiten. Zo verzekeren we dat de documentatie op een aantrekkelijke en gebruiksvriendelijke manier gepresenteerd wordt.
Wanneer je je documentatie host op een platform (zoals Netlify), kun je het met een aantal kliks zo configureren dat je als technisch schrijver niets meer moet doen voor het publiceren van updates. Aanpassingen kun je direct automatisch online laten komen of tegelijkertijd met de release van de code. Op die manier breng je je documentatie heel snel tot bij de gebruiker.
