Hoe softwaredocumentatie te schrijven: 8 stappen

Goede software-documentatie - Of het nu gaat om een document met de specificatie van vereisten voor programmeurs of testers, een technisch document voor interne gebruikers, de handleiding voor het gebruik van software of het programma prompts voor gebruikers - helpt een persoon die met software werkt, de kenmerkende kenmerken ervan en functies. Volg de tips - Hoe softwaredocumentatie te schrijven voor technische en eindgebruikers.

Stappen

Methode 1 van 2:

Software-documentatie schrijven voor technische gebruikers.

een. Bepalen welke informatie moet worden vermeld. Documenten over softwarevereisten dienen als referentiaal voor gebruikersinterface-ontwerpers, programmeurs die code en testers schrijven die controleren of de software als volgt werkt. Exacte informatie is echter afhankelijk van het programma zelf, kan echter het volgende omvatten:

Belangrijkste bestanden in de toepassing. Dit kunnen bestanden zijn die is gemaakt door het ontwikkelaarsteam, databases veroorzaakt tijdens de software-werking en de Service-programma`s van derden.
Functies en subroutines. Hier wordt aangegeven dat elke functie en subroutine maakt, inclusief invoer- en uitvoerwaarden.
Softwarevariabelen en constant en hoe ze worden gebruikt in de toepassing.
Algemene structuur van het programma. Voor schijfgebaseerde applicaties hebt u waarschijnlijk een beschrijving van afzonderlijke blokken en programmabibliotheken nodig, terwijl webtoepassingen een beschrijving van pagina`s nodig hebben die bestanden gebruiken.

Titel afbeelding Schrijf Software Documentatie Stap 2

2. Bepaal hoeveel documentatie zich in de programmacode bevindt en hoeveel moet worden gescheiden. Hoe meer de technische documentatie wordt gemaakt in de programmacode, hoe gemakkelijker het deze code zal bijwerken als documentatie met betrekking tot verschillende versies van de originele toepassing. Minimaal moet de documentatie in de programmacode de functies, subroutines, softwareconstanten en variabelen verklaren.

Als de programmacode vrij lang is, kan deze worden geplaatst als referentiebestand waarin u kunt zoeken op zoekwoorden of wegwijzers. Het zal een groot pluspunt zijn voor toepassingen waarbij de programma-logica is onderverdeeld in vele pagina`s en bevat extra bestandsnummers, zoals in bepaalde webtoepassingen.

Sommige programmeertalen, zoals Java of Net Framework (Visual Basic.Net, C #), hebben hun eigen normen voor documentatiecode. Volg in dergelijke gevallen de standaardinstructies - hoeveel documentatie moet worden opgenomen in de programmacode.

Titel afbeelding Schrijf Software Documentatie Stap 3

3. Kies een geschikte tool. Tot op zekere hoogte wordt dit gedefinieerd door de taal waarop de code is geschreven, of het nu C ++, C #, Visual Basic, Java of PHP is - voor elk zijn er onze eigen tool. In andere gevallen wordt het gebruikte hulpmiddel bepaald door het vereiste type documentatie.

Teksteditor "Microsoft Word" -Cercing-tool voor het maken van afzonderlijke tekstbestanden Documentatie die eenvoudig en kort is. Voor lange tekstbestanden kiezen veel technische documentatie-ontwikkelaars de voorkeur aan het Adobe-framemakerprogramma.

TIP-bestanden voor de documentatie van de softwarescode kunnen worden geschreven met behulp van een gereedschap, zoals RoboHelp, Help en Manual, Doc-to-Help, Madcap Flare of "HELPLOGIX".

Methode 2 van 2:

Software-documentatie schrijven voor eindgebruikers

een. Identificeer commerciële overwegingen voor uw documentatie. Hoewel functionele redenen voor softwaredocumentatie zijn om gebruikers te helpen begrijpen hoe de toepassing te gebruiken, zijn er andere redenen, zoals hulp bij het bevorderen van de goederen in de markt, het imago van het bedrijf en het belangrijkste te verbeteren, waardoor de technische ondersteuningskosten wordt verminderd. In bepaalde gevallen is de documentatie vereist om te voldoen aan bepaalde regels en wettelijke vereisten.

In geen geval mag de programmagedocumentatie geen slechte interfaceontwerp vervangen. Als het toepassingsscherm veel verklarende documentatie vereist, is het beter om het ontwerp te veranderen in iets intuïtiever.

Titel afbeelding Schrijf Software Documentatie Stap 5

2. Begrijp het publiek waarvoor u documentatie schrijft. In de meeste gevallen weten softwarebruikers weinig over computers naast applicatietaken. Er zijn verschillende manieren om te bepalen hoe ze hun behoeften met documentatie kunnen coördineren.

Kijk naar de beroepen die eigendom zijn van uw potentiële gebruikers. De systeembeheerder is waarschijnlijk een expert in het gebruik van softwaretoepassingen, terwijl de gegevensinvoeroperator waarschijnlijk de toepassing heeft die het of het momenteel gebruikt voor gegevensinvoer.

Kijk naar de gebruikers zelf. Hoewel hun berichten over het algemeen bepalen waar mensen mee bezig zijn, maar er zijn significante verschillen in hoe bepaalde posities in deze organisatie worden gebruikt. Het uitvoeren van een interview met potentiële gebruikers, u kunt uw mening toevoegen - voert de naam van de post voldoet aan de taken.

Zie de bestaande documentatie. Documentatie voor eerdere softwareversies geeft een geschatte concept dat de gebruiker moet weten over het gebruik van het programma. Onthoud echter dat de eindgebruikers niet geïnteresseerd zijn in hoe het programma werkt, het is belangrijk voor hen om te weten wat ze ermee kunnen doen.

Bepaal de taken die nodig zijn voor dit werk en welke taken moeten worden uitgevoerd voordat deze taken kunnen worden uitgevoerd.

Titel afbeelding Schrijf Software Documentatie Stap 6

3. Bepaal de juiste indeling (en) van documentatie. Software-documentatie kan worden gestructureerd in een van de twee indelingen - Referentiehandleiding en Gebruiksaanwijzing. Soms is het beter om een gemengde versie van deze twee indelingen te kiezen.

Referentiegids is ontworpen om de tools van de software (knoppen, tabellen, veld- en dialoogvenster) uit te leggen en hoe deze toolkit werkt. Veel snelle bestanden zijn in dit formaat geschreven en context-aanwijzingen helpen bij het zien van het gewenste onderwerp nadat de gebruiker op de knop "Help" op het gewenste scherm klikt.

Instructies voor gebruik wordt uitgelegd hoe u software kunt gebruiken om een specifieke taak uit te voeren. De gebruiksinstructie heeft vaak een gedrukte gids of PDF-formaat, hoewel sommige aanwijzingen onderwerpen bevatten over het uitvoeren van een specifieke taak. (Deze referentiethema`s zijn meestal niet contextueel, hoewel ze hyperlinks kunnen zijn) De gebruiksinstructie heeft vaak de vorm van een referentieboek met een taakbeschrijving en stapsgewijze instructies.

Titel afbeelding Schrijf Software Documentatie Stap 7

4. Bepaal welk formaat (formaten) van documentatie moet zijn. Software-documentatie voor eindgebruikers kan een of meer indelingen zijn: printhandleiding, documenten in PDF-formaat, tipbestanden of online hulp. Elk van deze indelingen is gemaakt om de gebruiker weer te geven om elke programmeerfunctie te gebruiken - of het nu een kort overzicht of gids is. Net als in het geval van snelle bestanden en online hulp, kan de documentatie een demonstratie video of tekst met afbeeldingen hebben.

Tips en online Help-bestanden moeten aanwijzingen hebben, zoeken op zoekwoorden, waarmee de gebruiker de vereiste informatie snel kan vinden. Hoewel de tools voor promptbestanden automatisch aanwijzers kunnen maken, is het beter om dit handmatig te doen met behulp van de termen die gebruikers waarschijnlijk zullen zoeken.

Titel afbeelding Write Software Documentatie Stap 8

vijf. Selecteer een geschikte tool voor het maken van documentatie. Printgidsen of PDF-formaat kunnen worden geschreven in tekstediteurs zoals "Word" of "Framemaker", afhankelijk van de lengte en complexiteit van de handleiding. TIP-bestanden kunnen worden geschreven met behulp van dergelijke ontwikkelingshulpmiddelen zoals "robohelp", "Hulp en handleiding", "DOC-to-Help", "Flare", "HELPLOGIX", of "HelpServer".

Tips

De tekst moet eenvoudig te lezen zijn, de afbeeldingen moeten zo dicht mogelijk bij de tekst worden geplaatst waartoe zij behoren. Schuif de documentatie voor secties en logische thema`s. Elke sectie of onderwerp moet betrekking hebben op een bepaalde vraag, of het nu gaat om één programma of taak. Gerelateerde vragen moeten worden aangegeven "om ook te bekijken" met een hyperlink, indien nodig.
Alle hulpmiddelen voor het maken van documentatie die hierboven zijn vermeld, kunnen worden aangevuld met het programma Screenshots, zoals Snagit, als de documentatie een bepaald aantal screenshots vereist. Net als bij de andere documentatie moeten screenshots uitleggen hoe de software werkt, en niet om de gebruiker te misleiden.
Ook belangrijk is de toon van het schrijven van documentatie, vooral als het is geschreven voor eindgebruikers. Gebruik het tweede gezicht "u", in plaats van een derde partij "gebruikers".

Wat je nodig hebt

Tool voor het schrijven van documentatie / debule
Tool voor het maken van schermafbeeldingen

Deel in het sociale netwerk: