Goede softwaredocumentatie, of het nu gaat om specificatiedocumentatie voor programmeurs en testers, technische documenten voor interne gebruikers of handleidingen en helpbestanden voor eindgebruikers, zal gebruikers helpen de kenmerken en functies van de software te begrijpen. Goede documentatie is documentatie die specifiek, duidelijk en relevant is, met alle informatie die de gebruiker nodig heeft. Dit artikel helpt u bij het schrijven van softwaredocumentatie voor technische gebruikers en eindgebruikers.
Stap
Methode 1 van 2: Softwaredocumentatie schrijven voor technische gebruikers
Stap 1. Weet welke informatie u moet opnemen
Het specificatiedocument wordt gebruikt als referentiehandleiding voor interfaceontwerpers, programmeurs die code schrijven en testers die de softwareprestaties verifiëren. De informatie die moet worden opgenomen, is afhankelijk van het programma dat wordt gemaakt, maar kan het volgende omvatten:
- Belangrijke bestanden in de applicatie, zoals bestanden die zijn gemaakt door het ontwikkelteam, databases die worden geopend terwijl het programma draait, en applicaties van derden.
- Functies en subroutines, inclusief uitleg over het gebruik van de functie/subroutine, invoer- en uitvoerwaarden.
- Programmeer variabelen en constanten, en hoe ze worden gebruikt.
- Algemene programmastructuur. Voor op stations gebaseerde programma's moet u mogelijk elke module en bibliotheek beschrijven. Of, als u een handleiding schrijft voor een webgebaseerd programma, moet u wellicht uitleggen welke bestanden elke pagina gebruikt.
Stap 2. Bepaal welk niveau van documentatie aanwezig moet zijn en kan worden gescheiden van de programmacode
Hoe meer technische documentatie er in de programmacode is opgenomen, hoe gemakkelijker het zal zijn om deze bij te werken en te onderhouden, evenals om de verschillende versies van het programma uit te leggen. De documentatie in de programmacode moet op zijn minst het gebruik van functies, subroutines, variabelen en constanten bevatten.
- Als uw broncode lang is, kunt u documentatie in een helpbestand schrijven, dat vervolgens met bepaalde trefwoorden kan worden geïndexeerd of doorzocht. Afzonderlijke documentatiebestanden zijn handig als de programmalogica is verdeeld over meerdere pagina's en ondersteuningsbestanden bevat, zoals een webtoepassing.
- Sommige programmeertalen (zoals Java, Visual Basic. NET of C#) hebben hun eigen codedocumentatiestandaarden. Volg in dergelijke gevallen de standaarddocumentatie die in de broncode moet worden opgenomen.
Stap 3. Selecteer de juiste documentatietool
In sommige gevallen wordt de documentatietool bepaald door de gebruikte programmeertaal. De talen C++, C#, Visual Basic, Java, PHP en andere hebben hun eigen documentatietools. Als dit niet het geval is, zijn de gebruikte tools echter afhankelijk van de vereiste documentatie.
- Een tekstverwerker zoals Microsoft Word is geschikt voor het maken van documenttekstbestanden, zolang de documentatie maar beknopt en eenvoudig is. Om lange documentatie met complexe tekst te maken, kiezen de meeste technische schrijvers voor een gespecialiseerde documentatietool, zoals Adobe FrameMaker.
- Help-bestanden voor het documenteren van de broncode kunnen worden gemaakt met een programma voor het genereren van ondersteunende bestanden, zoals RoboHelp, Help and Manual, Doc-To-Help, MadCap Flare of HelpLogix.
Methode 2 van 2: Softwaredocumentatie schrijven voor eindgebruikers
Stap 1. Ken de zakelijke redenen die ten grondslag liggen aan het maken van de handleiding
Hoewel de belangrijkste reden voor softwaredocumentatie is om gebruikers te helpen begrijpen hoe de applicatie te gebruiken, zijn er verschillende andere redenen die ten grondslag kunnen liggen aan het maken van documentatie, zoals het helpen van de marketingafdeling om de applicatie te verkopen, het verbeteren van het imago van het bedrijf en het verminderen van technische ondersteuning kosten. In sommige gevallen is documentatie vereist om te voldoen aan regelgeving of andere wettelijke vereisten.
Documentatie is echter geen goede vervanging voor een interface. Als een toepassing veel documentatie vereist om te kunnen werken, moet deze intuïtiever worden ontworpen
Stap 2. Ken de doelgroep van de documentatie
Over het algemeen hebben softwaregebruikers beperkte computerkennis buiten de applicaties die ze gebruiken. Er zijn verschillende manieren om aan hun documentatiebehoeften te voldoen:
- Let op de titel van de softwaregebruiker. Zo kent de systeembeheerder doorgaans verschillende computerapplicaties, terwijl de secretaresse alleen de applicaties kent waarmee hij gegevens invoert.
- Besteed aandacht aan softwaregebruikers. Hoewel hun functies over het algemeen compatibel zijn met de uitgevoerde taken, kunnen deze functies verschillende werklasten hebben, afhankelijk van de plaats van vestiging. Door potentiële gebruikers te interviewen, kunt u erachter komen of uw beoordeling van hun functietitel correct is.
- Besteed aandacht aan de bestaande documentatie. Documentatie en specificaties over softwarefunctionaliteit kunnen laten zien wat gebruikers moeten weten om ze te kunnen gebruiken. Houd er echter rekening mee dat gebruikers misschien niet geïnteresseerd zijn in het kennen van de "ingewanden" van het programma.
- Weet wat er nodig is om een taak te voltooien en wat er nodig is voordat u deze kunt voltooien.
Stap 3. Bepaal het juiste formaat voor de documentatie
Softwaredocumentatie kan in 1 of 2 formaten worden geregeld, namelijk naslagwerken en handleidingen. Soms is het combineren van de twee formaten een goede oplossing.
- Referentie-indelingen worden gebruikt om alle softwarefuncties, zoals knoppen, tabbladen, velden en dialoogvensters, te beschrijven en hoe ze werken. Sommige helpbestanden zijn in dit formaat geschreven, vooral die welke contextgevoelig zijn. Wanneer de gebruiker in een bepaald scherm op Help klikt, krijgt de gebruiker het betreffende onderwerp te zien.
- Het handmatige formaat wordt gebruikt om uit te leggen hoe u iets met de software kunt doen. Handleidingen zijn over het algemeen in gedrukte of PDF-formaat, hoewel sommige helppagina's ook instructies bevatten over hoe bepaalde dingen te doen. (Over het algemeen zijn handmatige indelingen niet contextgevoelig, maar kunnen ze worden gekoppeld aan contextgevoelige onderwerpen). Handboeken hebben over het algemeen de vorm van een gids, met een samenvatting van de uit te voeren taken in een beschrijving en een gids die in stappen is opgemaakt.
Stap 4. Bepaal het type documentatie
Softwaredocumentatie voor gebruikers kan zijn verpakt in een of meer van de volgende formaten: gedrukte handleidingen, PDF-bestanden, helpbestanden of online help. Elk type documentatie is ontworpen om u te laten zien hoe u de functies van de software gebruikt, of het nu een handleiding of een zelfstudie is. Online documentatie en helppagina's kunnen ook demonstratievideo's, tekst en statische afbeeldingen bevatten.
Online help- en ondersteuningsbestanden moeten worden geïndexeerd en doorzoekbaar met trefwoorden, zodat gebruikers snel de informatie kunnen vinden die ze nodig hebben. Hoewel een toepassing voor het genereren van helpbestanden automatisch een index kan maken, wordt toch aanbevolen dat u handmatig een index maakt met behulp van veelgebruikte trefwoorden
Stap 5. Selecteer de juiste documentatietool
Gedrukte handleidingen of PDF's kunnen worden gemaakt met een tekstverwerkingsprogramma zoals Word of een geavanceerde teksteditor zoals FrameMaker, afhankelijk van de lengte en complexiteit van het bestand. Help-bestanden kunnen worden geschreven met een programma voor het maken van helpbestanden, zoals RoboHelp, Help and Manual, Doc-To-Help, Flare, HelpLogix of HelpServer.
Tips
- De tekst van de programmadocumentatie moet zo zijn gestructureerd dat deze gemakkelijk te lezen is. Plaats de afbeelding zo dicht mogelijk bij de juiste tekst. Deel de documentatie logisch op in secties en onderwerpen. Elke sectie of elk onderwerp moet een specifiek probleem beschrijven, zowel taak- als programmafuncties. Verwante zaken kunnen worden uitgelegd met links of referentielijsten.
- Elk van de documentatietools die in dit artikel worden beschreven, kan worden aangevuld met een programma voor het maken van screenshots, zoals SnagIt als uw documentatie meerdere screenshots vereist. Net als bij elke andere documentatie, moet je ook screenshots toevoegen om uit te leggen hoe de app werkt, in plaats van de gebruiker te "verlokken".
- Aandacht besteden aan stijl is erg belangrijk, vooral als je softwaredocumentatie schrijft voor eindgebruikers. Spreek gebruikers aan met het voornaamwoord "u", in plaats van "gebruiker".
