Softwaredocumentatie schrijven voor eindgebruikers Softwaredocumentatie schrijven voor technische gebruikers
Hoewel de functionele reden voor het documenteren van software is om gebruikers te helpen bij het begrijpen hoe ze de toepassing moeten gebruiken, zijn er andere redenen, zoals assisteren bij de marketing van de software, verbetering van het bedrijfsimago en vooral minder kosten voor technische ondersteuning. In sommige gevallen is de documentatie noodzakelijk om te voldoen aan bepaalde regelgeving of andere wettelijke vereisten. In geen geval mag softwaredocumentatie echter een vervanging zijn voor slecht interfaceontwerp. Als een toepassing pagina's documentatie vereist als handleiding, dan is het beter om het schermontwerp te veranderen naar iets dat intuïtiever is. In de meeste gevallen hebben softwaregebruikers weinig kennis van computers buiten de taken die ze kunnen verrichten met de toepassingen die ze gebruiken. Er zijn verschillende manieren om te bepalen wat ze nodig hebben en hoe je documentatie daaraan kan voldoen.  Kijk naar de functies die je potentiële gebruikers hebben. Een systeembeheerder is waarschijnlijk een expert op het gebied van een aantal softwareapplicaties, terwijl een data-entrymedewerker waarschijnlijk alleen de toepassing kent waarvan hij of zij gebruikmaakt voor het invoeren van gegevens. Kijk naar de gebruikers zelf. Hoewel functietitels meestal aangeven wat mensen doen, kunnen er aanzienlijke verschillen zijn in hoe bepaalde functies worden ingevuld binnen een organisatie. Door potentiële gebruikers te interviewen kun je een idee krijgen of je indruk van wat hun functie aangeeft wel of niet klopt. Bekijk bestaande documentatie. Documentatie voor eerdere versies van de software (evenals functionele specificaties) geven een indicatie van wat de gebruiker moet weten om het programma te gebruiken. Houd echter in gedachten dat eindgebruikers niet echt geïnteresseerd zijn in hoe het programma werkt, als wel in wat het voor hen kan doen. Bepaal de taken die gedaan moeten worden om een opdracht uit te voeren, en welke taken moeten worden gedaan voordat die taken kunnen worden uitgevoerd. Softwaredocumentatie kan worden gestructureerd in 1 van 2 formaten: de handleiding en de gebruikershandleiding. Soms is een combinatie van beide formaten de beste aanpak.  Een referentiehandleiding is gewijd aan het verklaren van de afzonderlijke functies van een softwaretoepassing (knoppen, tabbladen, velden en dialoogvenster) en hoe ze werken. Veel helpbestanden zijn geschreven in dit formaat, met name contextafhankelijke hulp die een relevant onderwerp weergeeft wanneer een gebruiker op de knop Help klikt in een bepaald scherm. Een gebruikershandleiding legt uit hoe je de software kunt gebruiken om een bepaalde taak uit te voeren. Gebruikershandleidingen zijn vaak opgemaakt als gedrukte gidsen of PDF's, hoewel sommige helpbestanden onderwerpen bevatten over het uitvoeren van bepaalde taken. (Deze helponderwerpen zijn meestal niet contextafhankelijk, hoewel ze mogelijk gekoppeld zijn aan onderwerpen die dat wel zijn.) Gebruikershandleidingen komen vaak in de vorm van tutorials, met een overzicht van de taken die moeten worden uitgevoerd in de inleiding en instructies die zijn gegeven in genummerde stappen. Softwaredocumentatie kan vele vormen aannemen: handleidingen, pdfdocumenten, helpbestanden of online help. Elke vorm is ontworpen om de gebruiker het gebruik te tonen van elk van de functies van het programma, of in de vorm van een walkthrough of tutorial; in het geval van helpbestanden en online help kunnen dit zowel tekst als demonstratievideo's zijn, evenals afbeeldingen. Helpbestanden en online help dienen geïndexeerd te zijn en doorzoekbaar met zoekwoorden, waarmee gebruikers snel de informatie kunnen vinden die ze nodig hebben. Hoewel programma's voor het maken van helpbestanden automatisch indexen kunnen genereren, is het vaak beter om de index handmatig te maken, gebruikmakend van termen waar gebruikers meestal naar zullen zoeken. Gedrukte of pdf-handleidingen kunnen worden geschreven met een tekstverwerkingsprogramma zoals Word, of een geavanceerde teksteditor zoals FrameMaker, afhankelijk van de lengte en complexiteit ervan. Helpbestanden kunnen worden geschreven met een speciaal ontwerpgereedschap zoals RoboHelp, Help and Manual, Doc-To-Help, Flare, HelpLogix of HelpServer. 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. Dit kunnen bestanden zijn gemaakt door het ontwikkelteam, databases die worden geraadpleegd tijdens de werking van het programma, en hulpprogramma's van derden. Functies en subroutines. Het gaat hierbij om een uitleg van wat elke functie of subroutine doet, met inbegrip van alle invoerwaarden en uitvoerwaarden. Programmavariabelen en constanten, en hoe ze gebruikt worden in de toepassing. De algemene programmastructuur. Voor een schijf-gebaseerde applicatie, kan dit een beschrijving zijn van de individuele modules en bibliotheken van het programma, terwijl voor een webtoepassing dit kan beschrijven welke pagina's welke bestanden gebruiken. 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.  Als de broncode bijzonder lang is, kan het worden gedocumenteerd in de vorm van een helpbestand, welke kan worden geïndexeerd en doorzocht met zoekwoorden. Dit is een bijzonder voordeel voor toepassingen waarbij de programmalogica is versnipperd over vele pagina's en een aantal aanvullende bestanden bevat, zoals bij bepaalde webtoepassingen. Sommige programmeertalen, zoals Java en .NET Framework (Visual Basic.NET, C#), hebben hun eigen normen voor het documenteren van de code. Volg in deze gevallen de normen over de vraag hoeveel van de documentatie opgenomen dient te worden in de broncode. Tot op zekere hoogte wordt dit bepaald door de taal waarin de code is geschreven (zoals C++, C#, Visual Basic, Java of PHP), omdat er specifieke instrumenten bestaan voor deze en andere talen. In andere gevallen bepaald het type documentatie dat vereist is welke tool je moet gebruiken.  Tekstverwerkingsprogramma's voor Microsoft Word zijn voldoende voor het maken van afzonderlijke tekstbestanden voor documentatie, zolang de documentatie vrij kort en simpel is. Voor lange, complexe tekstbestanden geven veel technische schrijvers de voorkeur aan een documentatie-tool zoals Adobe FrameMaker. Helpbestanden voor het documenteren van de broncode kunnen worden geproduceerd met elk hulp-ontwerpgereedschap, zoals RoboHelp, Help and Manual, Doc-To-Help, MadCap Flare of HelpLogix.
Bepaal de zakelijke redenen voor je documentatie. Begrijp het publiek waarvoor je de documentatie schrijft. Bepaal het juiste formaat voor de documentatie. Beslis welke vorm de documentatie moet aannemen. Kies een geschikt documentatiegereedschap. Bepaal welke informatie moet worden opgenomen. Beslis hoeveel van de documentatie moet worden opgenomen in de programmacode en hoeveel afzonderlijk dient te worden gehouden. Kies het juiste documentatiegereedschap.
https://www.wikihow.com/Write-Software-Documentation https://www.wikihow.com/Write-Software-Documentation
Writing Software Documentation for End Users Writing Software Documentation for Technical Users