Hoe software documentatie te schrijven

Goede documentatie software, ofwel een specificatie document voor programmeurs en testers, een technisch document voor interne gebruikers, of software handleidingen en help documenten voor eindgebruikers, helpt de persoon die het werken met de software om de mogelijkheden ervan te begrijpen en functies. Goede gebruikersdocumentatie is specifiek, beknopt en relevant en geeft alle belangrijke informatie aan de persoon die de software gebruikt. Hieronder vindt u instructies over hoe je software documentatie voor technische gebruikers en eindgebruikers te schrijven worden gepresenteerd.

Inhoud

Stappen

Methode 1schrijf een softwaredocumentatie voor technische gebruikers
Methode 2schrijf softwaredocumentatie voor eindgebruikers

Tips
Dingen die je nodig hebt

stappen

Methode 1
Schrijf een softwaredocumentatie voor technische gebruikers

Titel afbeelding Write Software Documentation Step 1

Bepaalt welke informatie moet worden opgenomen. De softwarespecificatiedocumenten dienen als referentiehandleidingen voor de ontwerpers van de gebruikersinterface, de programmeurs die de code schrijven en de testers die controleren of de software correct werkt. De exacte informatie hangt af van het programma in kwestie, maar het kan een van de volgende dingen bevatten:

Essentiële bestanden binnen de applicatie. Dit kunnen de bestanden zijn die zijn gemaakt door het ontwikkelteam, de databases die zijn geopend door het bedrijfsprogramma en hulpprogramma`s van derden.
Functies en subroutines. Dit omvat een uitleg van wat elke subroutine of functie doet, inclusief de reikwijdte van de invoer- en uitvoerwaarden.
Variabelen en programma-constanten en hoe ze worden gebruikt in de toepassing.
De algemene structuur van het programma. Voor een toepassing die op de harde schijf werkt, kan het nodig zijn de afzonderlijke modules en bibliotheken van het programma te beschrijven, terwijl het voor een internettoepassing wellicht nodig is om te beschrijven welke pagina`s welke bestanden gebruiken.

Titel afbeelding Write Software Documentation Step 2

Bepaal hoeveel van de documentatie zich binnen de programmacode moet bevinden en hoeveel er uit elkaar moet zijn. Hoe meer u de technische documentatie ontwikkelt binnen de broncode van het programma, hoe eenvoudiger het zal zijn om het bij te werken en op een lijn te houden met de code, en het zal ook eenvoudiger zijn om de verschillende versies van de originele applicatie te documenteren. Minimaal moet de documentatie in de broncode het doel van de functies, subroutines, variabelen en constanten verklaren.

Als de broncode bijzonder lang is, kan deze worden gedocumenteerd in de vorm van een helpbestand, dat kan worden geïndexeerd of zoekopdrachten door trefwoorden kan toestaan. Dit is vooral voordelig voor toepassingen waarin de logica van het programma gefragmenteerd is over meerdere pagina`s en een aantal complementaire bestanden bevat, zoals het geval is bij bepaalde internettoepassingen.

Sommige programmeertalen, zoals Java en het .NET-framework (Visual Basic.NET, C #), hebben hun eigen regels voor het documenteren van de code. Volg in deze gevallen de regels over hoeveel van de documentatie bij de broncode moet worden gevoegd.

Titel afbeelding Write Software Documentation Step 3

Kies de juiste documentatietool. Tot op zekere hoogte wordt dit bepaald door de taal waarmee de code is geschreven, of C ++, C #, Visual Basic, Java of PHP, omdat er specifieke hulpmiddelen zijn voor deze en andere talen. In andere gevallen wordt de te gebruiken tool bepaald afhankelijk van het type documentatie dat nodig is.

Tekstverwerkers in Microsoft Word zijn geschikt om tekstbestanden in de documentatie afzonderlijk te maken, zolang de documentatie maar kort en eenvoudig is. Voor lange en complexe tekstbestanden geven veel technische schrijvers de voorkeur aan documentatiehulpmiddelen zoals Adobe FrameMaker.

U kunt helpbestanden maken om de broncode te documenteren met elk hulpmiddel om helpbestanden te maken, zoals RoboHelp, Help en handleiding, Doc-to-Help, MadCap Flare of HelpLogix.

Methode 2
Schrijf softwaredocumentatie voor eindgebruikers

Titel afbeelding Write Software Documentation Step 4

Bepaal de commerciële doeleinden van uw documentatie. Hoewel de functionele reden waarom de software is gedocumenteerd, is om gebruikers te helpen de toepassing te begrijpen, zijn er ook andere redenen, zoals het assisteren bij softwaremarketing, het verbeteren van het imago van het bedrijf en, nog belangrijker, het verlagen van de kosten. van technische ondersteuning. In sommige gevallen is documentatie nodig om te voldoen aan bepaalde voorschriften of wettelijke vereisten.

Softwaredocumentatie mag echter nooit een slecht interfaceontwerp compenseren. Als een toepassingsscherm pagina`s en pagina`s met documentatie nodig heeft om het uit te leggen, is het beter om het ontwerp van het scherm te wijzigen en iets meer intuïtief te doen.

Titel afbeelding Write Software Documentation Step 5

Begrijp voor wie u de documentatie schrijft. In de meeste gevallen weten softwaregebruikers weinig over computers buiten de taken die hen in staat stellen om de applicaties die ze gebruiken uit te voeren. Er zijn verschillende manieren om te bepalen hoe u aan uw behoeften kunt voldoen met behulp van documentatie.

Let op de professionele titels die uw potentiële gebruikers hebben. Een systeembeheerder kan een expert zijn in verschillende computerprogramma`s, terwijl een medewerker die gegevens invoert mogelijk alleen de toepassing kent die hij op dat moment gebruikt om de gegevens in te voeren.

Observeer de gebruikers zelf. Hoewel professionele titels meestal aangeven wat mensen doen, kan er een aanzienlijke variatie zijn in de manier waarop sommige titels in bepaalde organisaties worden gebruikt. Door potentiële gebruikers te interviewen, kunt u een idee hebben of u gelijk hebt wat u denkt dat hun professionele titel aangeeft.

Neem de bestaande documentatie in acht. De documentatie van de vorige versies van de software, evenals de functionele specificaties, geven enkele aanwijzingen over wat de gebruiker moet weten om het programma te gebruiken. Houd er echter rekening mee dat eindgebruikers niet geïnteresseerd zijn in hoe het programma werkt, maar wat het programma voor hen kan doen.

Identificeer de taken die nodig zijn om het werk uit te voeren, en welke taken moeten worden uitgevoerd voordat de andere taken kunnen worden uitgevoerd.

Titel afbeelding Write Software Documentation Step 6

Bepaal het juiste formaat (of geschikte formaten) voor de documentatie. De softwaredocumentatie kan worden gestructureerd in een van de twee indelingen, de referentiehandleiding en de gebruikershandleiding. Soms is de beste manier om een combinatie van beide formaten te gebruiken.

Een referentiehandleiding is gewijd aan het uitleggen van de individuele kenmerken van een software (knop, balk, veld en dialoogvenster) en hoe ze werken. Veel Help-bestanden zijn geschreven met behulp van deze indeling, vooral helpbestanden die rekening houden met de context en een relevant onderwerp weergeven wanneer de gebruiker op een bepaald scherm op de knop Help klikt.

In een gebruikershandleiding wordt uitgelegd hoe de software wordt gebruikt om een bepaalde taak uit te voeren. Gebruikershandleidingen worden meestal afgedrukt of in PDF-indeling, hoewel sommige Help-bestanden onderwerpen bevatten over het uitvoeren van specifieke taken (meestal houden deze Help-onderwerpen geen rekening met de context, hoewel ze mogelijk aan anderen zijn gekoppeld onderwerpen die dat wel doen). Over het algemeen zijn de gebruikershandleidingen in de vorm van zelfstudies, met een samenvatting van de taak die moet worden uitgevoerd in de inleiding en de instructies die in genummerde stappen worden weergegeven.

Titel afbeelding Write Software Documentation Step 7

Bepaal welke vorm (of formulieren) de documentatie moet aannemen. Softwaredocumentatie voor eindgebruikers kan verschillende vormen aannemen: gedrukte handleidingen, PDF-documenten, helpbestanden of online hulp. Elk van de formulieren is ontworpen om de gebruiker te laten zien hoe elke functie van het programma moet worden gebruikt, hetzij in de vorm van een stapsgewijze handleiding of een zelfstudie.In het geval van online-hulp en helpbestanden kunnen deze demonstratievideo`s bevatten. naast de tekst en de afbeeldingen.

De online helpbestanden moeten worden geïndexeerd en zoeken op trefwoorden toestaan zodat de gebruiker snel de informatie kan vinden waarnaar hij op zoek is. Hoewel de hulpprogramma`s voor het maken van de helpbestanden automatisch de indexen kunnen genereren, is het meestal beter om ze handmatig te maken met behulp van de termen waarnaar de gebruikers waarschijnlijk zullen zoeken.

Titel afbeelding Write Software Documentation Step 8

Kies de juiste documentatietool. De gedrukte of PDF-gebruikershandleidingen kunnen worden geschreven met een tekstverwerker zoals Word of een geavanceerde teksteditor zoals FrameMaker, afhankelijk van de lengte en complexiteit. Help-bestanden kunnen met tools worden geschreven om helpbestanden te maken, zoals RoboHelp, Help en Manual, Doc-To-Help, Flare of HelpLogix.

tips

De tekst moet zo zijn georganiseerd dat deze gemakkelijk kan worden gelezen, waarbij de afbeeldingen zo dicht mogelijk bij de tekst worden geplaatst die ernaar verwijst. Scheid de documentatie in secties en onderwerpen op een logische manier. Elke sectie of elk onderwerp moet één probleem behandelen, of het nu gaat om een enkele functie of taak van het programma. Verwante onderwerpen kunnen worden behandeld met behulp van "zie ook" lijsten of hyperlinks, indien nodig.
Elk van de bovengenoemde documentatiehulpmiddelen kan worden aangevuld met een programma waarmee u schermafbeeldingen kunt maken, zoals Snagit, als de documentatie enkele schermafbeeldingen vereist. Net als bij andere documentatie, moeten opnames worden opgenomen om te helpen verklaren hoe het programma werkt, niet om de gebruiker te verblinden.
Toon is vooral belangrijk, vooral bij het schrijven van softwaredocumentatie voor eindgebruikers. Noem de gebruiker die de tweede persoon "jij" gebruikt in plaats van de derde persoon "de gebruikers" te gebruiken.