Het schrijven van goede documentatie vereist echter een aantal vaardigheden en aandachtspunten. Hier zijn enkele tips om je te helpen bij het schrijven van documentatie voor software:

• Bepaal welke informatie moet worden opgenomen. Softwarespecificaties dienen als handleidingen voor ontwerpers van de gebruikersinterface, programmeurs die de code schrijven en testers die controleren of de software werkt zoals de bedoeling is. De exacte informatie hangt af van het programma in kwestie, maar kan een van de volgende onderdelen bevatten: de belangrijkste bestanden binnen de toepassing, functies en subroutines, programmavariabelen en constanten, en de algemene programmastructuur.
  
  
• Beslis hoeveel van de documentatie moet worden opgenomen in de programmacode en hoeveel afzonderlijk dient te worden gehouden. Hoe meer technische documentatie al ontwikkeld is binnen de broncode van het programma, hoe makkelijker het zal zijn om dit samen met de code te updaten en onderhouden, evenals het documenteren van verschillende versies van de oorspronkelijke applicatie. Minimaal moet documentatie binnen de broncode uitleggen wat het doel is van functies, subroutines, variabelen en constanten. Sommige programmeertalen hebben hun eigen normen voor het documenteren van de code.
  
  
• Gebruik een duidelijke en consistente stijl en terminologie. Zorg ervoor dat je documentatie leesbaar, begrijpelijk en nauwkeurig is. Gebruik een eenvoudige en directe taal, vermijd jargon en ambiguïteit, en wees consistent in het gebruik van termen en afkortingen. Gebruik ook een uniforme opmaak en indeling voor je documentatie, zodat het gemakkelijk te volgen en te raadplegen is.
  
  
• Houd je documentatie up-to-date. Documentatie is alleen nuttig als het overeenkomt met de huidige staat van de software. Zorg ervoor dat je je documentatie regelmatig bijwerkt als er wijzigingen of verbeteringen worden aangebracht in de software. Vermeld ook altijd een datum en een versienummer in je documentatie, zodat je kunt bijhouden welke versie van de software bij welke versie van de documentatie hoort.
  
  
• Laat je documentatie controleren door anderen. Het is altijd goed om feedback te krijgen van andere ontwikkelaars, gebruikers of experts die je documentatie kunnen lezen en beoordelen. Zij kunnen je wijzen op eventuele fouten, onduidelijkheden of ontbrekende informatie in je documentatie. Vraag hen om je documentatie kritisch te lezen en te verbeteren waar nodig. Vermeld ook altijd wie je documentatie heeft gereviseerd of goedgekeurd in je document.

Marnix zijn tips

Hier zijn 10 tips van Marnix Bouwman voor het schrijven van goede documentatie:

1. Weet wie je doelgroep is en schrijf op hun niveau.
2. Gebruik duidelijke en beknopte taal.
3. Gebruik afbeeldingen en video’s om complexe concepten uit te leggen.
4. Maak gebruik van opsommingstekens en nummering om informatie gemakkelijker te begrijpen.
5. Gebruik een consistente lay-out en opmaak.
6. Zorg ervoor dat de documentatie up-to-date is.
7. Geef voorbeelden van het gebruik van de software.
8. Geef antwoorden op veelgestelde vragen.
9. Maak gebruik van hyperlinks om gerelateerde informatie te delen.
10. Laat anderen de documentatie lezen en feedback geven.