Hoe om dokumentasie vir sagteware te skryf: 8 stappe (met prente)

Inhoud

Trappe
- Metode 1 van 2: Skryf sagteware dokumentasie vir tegniese gebruikers
- Metode 2 van 2: Skryf sagteware dokumentasie vir eindgebruikers
Wenke
Benodigdhede

Goeie sagtewaredokumentasie, of dit nou `n spesifikasiedokument vir programmeerders en toetsers is, `n tegniese dokument vir kollegas, of sagtewarehandleidings en hulplêers vir eindgebruikers, help die persoon wat met die sagteware moet werk om al sy kenmerke en funksies te verstaan. Goeie sagtewaredokumentasie is spesifiek, bondig en relevant en verskaf alle belangrike inligting aan die persoon wat die sagteware gebruik. Hieronder vind u instruksies oor hoe om sagtewaredokumentasie vir tegniese gebruikers en eindgebruikers te skryf.

Trappe

Metode 1 van 2: Skryf sagteware dokumentasie vir tegniese gebruikers

Prent getiteld Skryf sagtewaredokumentasie Stap 1

1. Besluit watter inligting om in te sluit. Sagteware spesifikasies dien as gidse vir gebruikerskoppelvlakontwerpers, programmeerders wat die kode skryf en toetsers wat verifieer dat die sagteware werk soos bedoel. Die presiese inligting hang af van die betrokke program, maar kan enige van die volgende insluit:

Die belangrikste lêers binne die toepassing. Dit kan lêers wees wat deur die ontwikkelingspan geskep is, databasisse waartoe toegang verkry is tydens die werking van die program, en derdeparty-nutsprogramme.
Funksies en subroetines. Dit is `n verduideliking van wat elke funksie of subroetine doen, insluitend alle invoer- en uitvoerwaardes.
Programveranderlikes en konstantes, en hoe hulle in die toepassing gebruik word.
Die algemene programstruktuur. Vir `n skyfgebaseerde toepassing kan dit `n beskrywing van die program se individuele modules en biblioteke wees, terwyl dit vir `n webtoepassing kan beskryf watter bladsye watter lêers gebruik.

Prent getiteld Skryf sagtewaredokumentasie Stap 2

2. Besluit hoeveel van die dokumentasie by die programkode ingesluit moet word en hoeveel apart gehou moet word. Hoe meer tegniese dokumentasie reeds binne die bronkode van die program ontwikkel is, hoe makliker sal dit wees om dit saam met die kode op te dateer en in stand te hou, asook om verskillende weergawes van die oorspronklike toepassing te dokumenteer. Dokumentasie binne bronkode moet ten minste die doel van funksies, subroetines, veranderlikes en konstantes verduidelik.

As die bronkode besonder lank is, kan dit gedokumenteer word in die vorm van `n hulplêer, wat geïndekseer en met sleutelwoorde deursoek kan word. Dit is `n besondere voordeel vir toepassings waar die programlogika oor baie bladsye gefragmenteer is en `n aantal bykomende lêers bevat, soos met sekere webtoepassings.

Sommige programmeertale, soos Java en .NET Framework (Visual Basic.NET, C#), het hul eie standaarde vir die dokumentasie van die kode. In hierdie gevalle, volg die standaarde oor hoeveel van die dokumentasie in die bronkode ingesluit moet word.

Prent getiteld Skryf sagtewaredokumentasie Stap 3

3. Kies die regte dokumentasie-instrument. Dit word tot `n mate bepaal deur die taal waarin die kode geskryf is (soos C++, C#, Visual Basic, Java of PHP), aangesien spesifieke hulpmiddels vir hierdie en ander tale bestaan. In ander gevalle bepaal die tipe dokumentasie wat benodig word watter instrument om te gebruik.

Woordverwerkingsprogramme vir Microsoft Word is voldoende om aparte tekslêers vir dokumentasie te skep, solank die dokumentasie redelik kort en eenvoudig is. Vir lang, komplekse tekslêers verkies baie tegniese skrywers `n dokumentasie-instrument soos Adobe FrameMaker.

Hulplêers vir die dokumentasie van die bronkode kan geproduseer word met enige hulp outeursinstrument, soos RoboHelp, Help and Manual, Doc-To-Help, MadCap Flare, of HelpLogix.

Metode 2 van 2: Skryf sagteware dokumentasie vir eindgebruikers

Prent getiteld Skryf sagtewaredokumentasie Stap 4

1. Bepaal die besigheidsredes vir jou dokumentasie. Alhoewel die funksionele rede vir die dokumentasie van sagteware is om gebruikers te help verstaan hoe om die toepassing te gebruik, is daar ander redes soos om te help met die bemarking van die sagteware, die verbetering van korporatiewe beeld en bowenal die vermindering van tegniese ondersteuningskoste. In sommige gevalle is die dokumentasie nodig om aan sekere regulasies of ander wetlike vereistes te voldoen.

Sagtewaredokumentasie behoort egter geensins `n plaasvervanger vir swak koppelvlakontwerp te wees nie. As `n toepassing bladsye van dokumentasie as `n gids vereis, is dit beter om die skermontwerp na iets meer intuïtief te verander.

Prent getiteld Skryf sagtewaredokumentasie Stap 5

2. Verstaan die gehoor vir wie jy die dokumentasie skryf. In die meeste gevalle het sagtewaregebruikers min kennis van rekenaars behalwe die take wat hulle kan verrig met die toepassings wat hulle gebruik. Daar is verskeie maniere om te bepaal wat hulle nodig het en hoe jou dokumentasie daaraan kan voldoen.

Kyk na die kenmerke wat jou potensiële gebruikers het. `n Stelseladministrateur sal waarskynlik `n kenner van `n aantal sagtewaretoepassings wees, terwyl `n data-invoerklerk waarskynlik net die toepassing sal ken wat hy of sy gebruik om data in te voer.

Kyk na die gebruikers self. Terwyl postitels gewoonlik aandui wat mense doen, kan daar beduidende verskille wees in hoe sekere poste binne `n organisasie gevul word. Deur onderhoude te voer met potensiële gebruikers kan jy `n idee kry of jou indruk van wat hul posisie aandui korrek is of nie.

Bekyk bestaande dokumentasie. Dokumentasie vir vorige weergawes van die sagteware (asook funksionele spesifikasies) verskaf `n aanduiding van wat die gebruiker moet weet om die program te gebruik. Hou egter in gedagte dat eindgebruikers nie regtig belangstel in hoe die program werk nie, maar in wat dit vir hulle kan doen.

Bepaal die take wat gedoen moet word om `n opdrag te voltooi, en watter take gedoen moet word voordat daardie take uitgevoer kan word.

Prent getiteld Skryf sagtewaredokumentasie Stap 6

3. Bepaal die korrekte formaat vir die dokumentasie. Sagtewaredokumentasie kan in 1 van 2 formate gestruktureer word: die handleiding en die gebruikershandleiding. Soms is `n kombinasie van beide formate die beste benadering.

`n Verwysingsgids word gewy aan die verduideliking van die individuele funksies van `n sagtewaretoepassing (knoppies, oortjies, velde en dialoogkassie) en hoe dit werk. Baie hulplêers is in hierdie formaat geskryf, veral konteks-sensitiewe hulp wat `n relevante onderwerp vertoon wanneer `n gebruiker die Help-knoppie op `n spesifieke skerm klik.

`n Gebruikersgids verduidelik hoe om die sagteware te gebruik om `n spesifieke taak uit te voer. Gebruikershandleidings word dikwels as gedrukte gidse of PDF`s geformateer, hoewel sommige hulplêers onderwerpe bevat oor hoe om sekere take uit te voer. (Hierdie hulponderwerpe is gewoonlik nie konteksafhanklik nie, alhoewel hulle gekoppel kan wees aan onderwerpe wat wel is.) Gebruikersgidse kom dikwels in die vorm van tutoriale, met `n oorsig van die take wat in die inleiding uitgevoer moet word en instruksies gegee in genommerde stappe.

Prent getiteld Skryf sagtewaredokumentasie Stap 7

4. Besluit watter vorm die dokumentasie moet aanneem. Sagtewaredokumentasie kan baie vorme aanneem: handleidings, PDF-dokumente, hulplêers of aanlynhulp. Elke vorm is ontwerp om die gebruiker die gebruik van elk van die program se kenmerke te wys, hetsy in die vorm van `n deurloop of tutoriaal; in die geval van hulplêers en aanlynhulp, kan dit teks sowel as demonstrasievideo`s sowel as beelde wees.

Hulplêers en aanlynhulp moet geïndekseer en deursoekbaar wees met sleutelwoorde, sodat gebruikers vinnig die inligting kan vind wat hulle benodig. Terwyl hulplêerbouers outomaties indekse kan genereer, is dit dikwels beter om die indeks met die hand te skep deur terme te gebruik waarna gebruikers gewoonlik sal soek.

Prent getiteld Skryf sagtewaredokumentasie Stap 8

5. Kies `n geskikte dokumentasie-instrument. Gedrukte of PDF-handleidings kan geskryf word met `n woordverwerkingsprogram soos Word, of `n gevorderde teksredigeerder soos FrameMaker, afhangende van hul lengte en kompleksiteit. Hulplêers kan geskryf word met `n spesiale outeursinstrument soos RoboHelp, Help and Manual, Doc-To-Help, Flare, HelpLogix of HelpServer.

Wenke

Die teks moet georganiseer word om maklik te lees, met beelde so na as moontlik aan die teks waarna dit verwys. Verdeel die dokumentasie logies in paragrawe, afdelings en onderwerpe. Elke paragraaf of onderwerp moet `n enkele kwessie verduidelik, of dit nou `n enkele programfunksie of `n taak is. Verwante kwessies kan verduidelik word, waar toepaslik, deur gebruik te maak van `Sien ook`-lyste of hiperskakels soos hierbo genoem.
Enige van die dokumentasiehulpmiddels wat hierbo gelys word, kan aangevul word met `n skermkiekieprogram, soos Snagit, as die dokumentasie sommige skermkiekies vereis. Soos met ander dokumentasie, moet skermkiekies ingesluit word om te help verduidelik hoe die sagteware werk, nie om die gebruiker te verwar nie.
Toon is baie belangrik, veral wanneer sagtewaredokumentasie vir eindgebruikers geskryf word. Spreek gebruikers aan in die tweede persoon ("jy") in plaas van die derde persoon ("gebruiker").