Documentatie schrijven voor software

Pdf downloaden
Pdf downloaden

Goede softwaredocumentatie, of het nu gaat om een document met specificaties voor programmeurs en testers, een technisch document voor collega's, of softwarehandleidingen en helpbestanden voor eindgebruikers, helpt de persoon die met de software moet werken bij het begrijpen van alle eigenschappen en functies ervan. Goede softwaredocumentatie is specifiek, beknopt en relevant, en verstrekt alle belangrijke informatie aan de persoon die gebruikmaakt van de software. Hieronder vind je instructies over het schrijven van softwaredocumentatie voor technische gebruikers en eindgebruikers.

Methode 1
Methode 1 van 2:

Softwaredocumentatie schrijven voor technische gebruikers

Pdf downloaden
  1. {"smallUrl":"https:\/\/www.wikihow.com\/images_en\/thumb\/5\/57\/Write-Software-Documentation-Step-1.jpg\/v4-460px-Write-Software-Documentation-Step-1.jpg","bigUrl":"https:\/\/www.wikihow.com\/images\/thumb\/5\/57\/Write-Software-Documentation-Step-1.jpg\/v4-728px-Write-Software-Documentation-Step-1.jpg","smallWidth":460,"smallHeight":345,"bigWidth":728,"bigHeight":546,"licensing":"<div class=\"mw-parser-output\"><\/div>"}
    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.
  2. {"smallUrl":"https:\/\/www.wikihow.com\/images_en\/thumb\/6\/6f\/Write-Software-Documentation-Step-2.jpg\/v4-460px-Write-Software-Documentation-Step-2.jpg","bigUrl":"https:\/\/www.wikihow.com\/images\/thumb\/6\/6f\/Write-Software-Documentation-Step-2.jpg\/v4-728px-Write-Software-Documentation-Step-2.jpg","smallWidth":460,"smallHeight":345,"bigWidth":728,"bigHeight":546,"licensing":"<div class=\"mw-parser-output\"><\/div>"}
    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.
    • 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.
  3. {"smallUrl":"https:\/\/www.wikihow.com\/images_en\/thumb\/8\/85\/Write-Software-Documentation-Step-3.jpg\/v4-460px-Write-Software-Documentation-Step-3.jpg","bigUrl":"https:\/\/www.wikihow.com\/images\/thumb\/8\/85\/Write-Software-Documentation-Step-3.jpg\/v4-728px-Write-Software-Documentation-Step-3.jpg","smallWidth":460,"smallHeight":345,"bigWidth":728,"bigHeight":546,"licensing":"<div class=\"mw-parser-output\"><\/div>"}
    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.
    Advertentie
Methode 2
Methode 2 van 2:

Softwaredocumentatie schrijven voor eindgebruikers

Pdf downloaden
  1. {"smallUrl":"https:\/\/www.wikihow.com\/images_en\/thumb\/8\/85\/Write-Software-Documentation-Step-4.jpg\/v4-460px-Write-Software-Documentation-Step-4.jpg","bigUrl":"https:\/\/www.wikihow.com\/images\/thumb\/8\/85\/Write-Software-Documentation-Step-4.jpg\/v4-728px-Write-Software-Documentation-Step-4.jpg","smallWidth":460,"smallHeight":345,"bigWidth":728,"bigHeight":546,"licensing":"<div class=\"mw-parser-output\"><\/div>"}
    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.
  2. {"smallUrl":"https:\/\/www.wikihow.com\/images_en\/thumb\/3\/35\/Write-Software-Documentation-Step-5.jpg\/v4-460px-Write-Software-Documentation-Step-5.jpg","bigUrl":"https:\/\/www.wikihow.com\/images\/thumb\/3\/35\/Write-Software-Documentation-Step-5.jpg\/v4-728px-Write-Software-Documentation-Step-5.jpg","smallWidth":460,"smallHeight":345,"bigWidth":728,"bigHeight":546,"licensing":"<div class=\"mw-parser-output\"><\/div>"}
    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.
  3. {"smallUrl":"https:\/\/www.wikihow.com\/images_en\/thumb\/5\/5b\/Write-Software-Documentation-Step-6.jpg\/v4-460px-Write-Software-Documentation-Step-6.jpg","bigUrl":"https:\/\/www.wikihow.com\/images\/thumb\/5\/5b\/Write-Software-Documentation-Step-6.jpg\/v4-728px-Write-Software-Documentation-Step-6.jpg","smallWidth":460,"smallHeight":345,"bigWidth":728,"bigHeight":546,"licensing":"<div class=\"mw-parser-output\"><\/div>"}
    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.
  4. {"smallUrl":"https:\/\/www.wikihow.com\/images_en\/thumb\/d\/d9\/Write-Software-Documentation-Step-7.jpg\/v4-460px-Write-Software-Documentation-Step-7.jpg","bigUrl":"https:\/\/www.wikihow.com\/images\/thumb\/d\/d9\/Write-Software-Documentation-Step-7.jpg\/v4-728px-Write-Software-Documentation-Step-7.jpg","smallWidth":460,"smallHeight":345,"bigWidth":728,"bigHeight":546,"licensing":"<div class=\"mw-parser-output\"><\/div>"}
    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.
  5. {"smallUrl":"https:\/\/www.wikihow.com\/images_en\/thumb\/f\/fd\/Write-Software-Documentation-Step-8.jpg\/v4-460px-Write-Software-Documentation-Step-8.jpg","bigUrl":"https:\/\/www.wikihow.com\/images\/thumb\/f\/fd\/Write-Software-Documentation-Step-8.jpg\/v4-728px-Write-Software-Documentation-Step-8.jpg","smallWidth":460,"smallHeight":345,"bigWidth":728,"bigHeight":546,"licensing":"<div class=\"mw-parser-output\"><\/div>"}
    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.
    Advertentie

Tips

  • De tekst moet worden geordend om gemakkelijk leesbaar te zijn, met afbeeldingen zo dicht mogelijk bij de tekst waar het naar verwijst. Deel de documentatie logisch op in paragrafen secties en onderwerpen. Elke paragraaf of onderwerp moet een enkele kwestie uitleggen, zij het een enkele programmafunctie of een taak. Aanverwante kwesties kunnen, daar waar nodig, worden uitgelegd met 'Zie ook'-lijsten of hyperlinks zoals hierboven vermeld.
  • Elk van de hierboven aangegeven documentatie-tools kunnen worden aangevuld met een screenshotprogramma, zoals Snagit, als de documentatie een aantal screenshots vereist. Net als bij andere documentatie, moeten screenshots worden opgenomen om te helpen bij het uitleggen hoe de software werkt, niet om de gebruiker te verwarren.
  • Toon is bijzonder belangrijk, zeker bij het schrijven van softwaredocumentatie voor eindgebruikers. Spreek gebruikers aan in de tweede persoon ('u') in plaats van de derde persoon ('gebruiker').
Advertentie

Benodigdheden

  • Hulpprogramma voor softwaredocumentatie/helpbestanden
  • Hulpprogramma voor screenshots

Gerelateerde artikelen

Een mooie handtekening maken
Een vriendelijke herinneringsmail schrijven
Een uitgedroogde balpen weer aan het schrijven krijgen
Een brief opvouwen en in een envelop stoppen
Een persoonlijke brief schrijven
Inkt van papier verwijderen
Een enveloppe per adres van iemand anders adresseren
Hoe kun je een uitgedroogde markeerstift nieuw leven inblazen?
Een welkomstspeech schrijven
Steno leren
Een limerick schrijven
Een script schrijven
Advertentie

Bronnen

  1. http://www.softwaredocumentation.info/DocumentingSoftware.aspx
  2. http://www.techscribe.co.uk/ta/how-to-write-user-documentation.htm
  3. http://www.techscribe.co.uk/ta/how-to-write-instructions.htm
  4. Rodney Ruff, Omaha, NE; experience as technical writer/help file author since 1997

Over dit artikel

In andere talen
Deze pagina is 4.844 keer bekeken.

Was dit artikel nuttig?

Advertentie