Goeie sagtewaredokumentasie, of dit nou spesifikasie -dokumentasie vir programmeerders en toetsers is, tegniese dokumente vir interne gebruikers, of handleidings en hulplêers vir eindgebruikers, sal gebruikers help om die funksies en funksies van die sagteware te verstaan. Goeie dokumentasie is 'n spesifieke, duidelike en relevante dokumentasie met al die inligting wat die gebruiker benodig. Hierdie artikel sal u lei om sagtewaredokumentasie vir tegniese gebruikers en eindgebruikers te skryf.
Stap
Metode 1 van 2: Skryf sagteware dokumentasie vir tegniese gebruikers
Stap 1. Weet watter inligting u moet insluit
Die spesifikasiedokument word gebruik as 'n verwysingshandleiding vir koppelvlakontwerpers, programmeerders wat kode skryf en toetsers wat die werkverrigting van die sagteware verifieer. Die inligting wat ingesluit moet word, sal afhang van die program wat geskep word, maar kan die volgende insluit:
- Belangrike lêers in die toepassing, soos lêers wat deur die ontwikkelingspan geskep is, databasisse waartoe toegang verkry is terwyl die program loop, en toepassings van derde partye.
- Funksies en subroutines, insluitend 'n verduideliking van die gebruik van die funksie/subroutine, invoer- en uitsetwaardes.
- Program veranderlikes en konstantes, en hoe hulle gebruik word.
- Algehele programstruktuur. Vir dryfgebaseerde programme moet u moontlik elke module en biblioteek beskryf. Of as u 'n handleiding vir 'n webgebaseerde program skryf, moet u moontlik verduidelik watter lêers elke bladsy gebruik.
Stap 2. Besluit watter vlak van dokumentasie teenwoordig moet wees en losgemaak kan word van die programkode
Hoe meer tegniese dokumentasie die programkode bevat, hoe makliker sal dit wees om dit op te dateer en in stand te hou, asook om die verskillende weergawes van die program te verduidelik. Die dokumentasie in die programkode moet ten minste die gebruik van funksies, subroetines, veranderlikes en konstantes insluit.
- As u bronkode lank is, kan u dokumentasie in 'n hulplêer skryf, wat dan met sekere sleutelwoorde geïndekseer of deursoek kan word. Afsonderlike dokumentasie lêers is handig as die programlogika oor verskeie bladsye verdeel is en ondersteuningslêers insluit, soos 'n webtoepassing.
- Sommige programmeertale (soos Java, Visual Basic. NET of C#) het hul eie kodedokumentasiestandaarde. Volg in sulke gevalle die standaard dokumentasie wat in die bronkode ingesluit moet word.
Stap 3. Kies die toepaslike dokumentasiehulpmiddel
In sommige gevalle word die dokumentasiehulpmiddel bepaal deur die programmeertaal wat gebruik word. Die tale C ++, C#, Visual Basic, Java, PHP en ander het hul eie dokumentasie -instrumente. Indien nie, sal die gereedskap wat gebruik word, afhang van die vereiste dokumentasie.
- 'N Woordverwerker soos Microsoft Word is geskik vir die skep van dokumenttekslêers, solank die dokumentasie bondig en eenvoudig is. Om lang dokumentasie met komplekse teks te skep, kies die meeste tegniese skrywers 'n gespesialiseerde dokumentasiehulpmiddel, soos Adobe FrameMaker.
- Hulplêers vir die dokumentasie van bronkode kan geskep word met 'n ondersteuningslêergeneratorprogram, soos RoboHelp, Help and Manual, Doc-To-Help, MadCap Flare of HelpLogix.
Metode 2 van 2: Skryf sagteware dokumentasie vir eindgebruikers
Stap 1. Ken die besigheidsredes wat ten grondslag lê by die opstel van die handleiding
Die belangrikste rede vir sagtewaredokumentasie is om gebruikers te help verstaan hoe om die toepassing te gebruik, maar daar is verskeie ander redes wat dokumentasie kan skep, soos om die bemarkingsafdeling te help om die aansoek te verkoop, die beeld van die onderneming te verbeter en tegniese ondersteuning te verminder koste. In sommige gevalle is dokumentasie nodig om aan die regulasies of ander wetlike vereistes te voldoen.
Dokumentasie is egter nie 'n goeie plaasvervanger vir 'n koppelvlak nie. As 'n toepassing baie dokumentasie benodig om te werk, moet dit meer intuïtief ontwerp word
Stap 2. Ken die teikengehoor van die dokumentasie
Oor die algemeen het sagtewaregebruikers beperkte rekenaarkennis bo die toepassings wat hulle gebruik. Daar is verskillende maniere om aan hul dokumentasiebehoeftes te voldoen:
- Gee aandag aan die titel van die sagteware -gebruiker. Die stelseladministrateur verstaan byvoorbeeld oor die algemeen verskillende rekenaartoepassings, terwyl die sekretaris slegs die toepassings ken wat hy gebruik om data in te voer.
- Gee aandag aan sagteware -gebruikers. Alhoewel hul posisies oor die algemeen verenigbaar is met die take wat uitgevoer word, kan hierdie posisies verskillende werkslading hê, afhangende van die plek van besigheid. Deur onderhoude met potensiële gebruikers te maak, kan u uitvind of u beoordeling van hul postitel korrek is.
- Gee aandag aan die bestaande dokumentasie. Sagteware funksionaliteit dokumentasie en spesifikasies kan wys wat gebruikers moet weet om dit te kan gebruik. Hou egter in gedagte dat gebruikers moontlik nie geïnteresseerd is in die 'binneste' van die program nie.
- Weet wat nodig is om 'n taak te voltooi en wat nodig is voordat u dit kan voltooi.
Stap 3. Bepaal die toepaslike formaat vir die dokumentasie
Sagteware dokumentasie kan in 1 of 2 formate gereël word, naamlik naslaanboeke en handleidings. Soms is die kombinasie van die twee formate 'n goeie oplossing.
- Verwysingsformate word gebruik om alle sagtewarefunksies, soos knoppies, oortjies, velde en dialoogkaste, en hoe dit werk, te beskryf. Sommige hulplêers word in hierdie formaat geskryf, veral konteksgevoelig. As die gebruiker op 'n sekere skerm op Help klik, ontvang die gebruiker die relevante onderwerp.
- Die handmatige formaat word gebruik om te verduidelik hoe u iets met die sagteware moet doen. Handleidings is gewoonlik in druk- of PDF -formaat, hoewel sommige hulpbladsye ook instruksies bevat oor hoe om sekere dinge te doen. (Handmatige formate is oor die algemeen nie konteksgevoelig nie, maar kan gekoppel word aan kontekssensitiewe onderwerpe). Handboeke is oor die algemeen in die vorm van 'n gids, met 'n opsomming van die take wat in 'n beskrywing uitgevoer moet word en 'n gids wat in stappe geformateer is.
Stap 4. Besluit oor die tipe dokumentasie
Sagteware -dokumentasie vir gebruikers kan in een of meer van die volgende formate verpak word: gedrukte handleidings, PDF -lêers, hulplêers of aanlynhulp. Elke tipe dokumentasie is ontwerp om u te wys hoe u die funksies van die sagteware kan gebruik, of dit nou 'n gids of 'n handleiding is. Aanlyn dokumentasie en hulpbladsye kan ook demonstrasievideo's, teks en statiese beelde insluit.
Aanlyn hulp- en ondersteuningslêers moet geïndekseer en soekbaar wees met behulp van sleutelwoorde, sodat gebruikers vinnig die inligting kan kry wat hulle benodig. Alhoewel 'n hulp -lêergenerator -toepassing outomaties 'n indeks kan skep, word dit steeds aanbeveel dat u 'n indeks handmatig maak met behulp van algemene soekde sleutelwoorde
Stap 5. Kies die toepaslike dokumentasiehulpmiddel
Afhangende van die lengte en kompleksiteit van die lêer, kan gedrukte handleidings of PDF's geskep word met 'n woordverwerkingsprogram soos Word of 'n gevorderde teksredakteur soos FrameMaker. Hulplêers kan geskryf word met 'n hulp-skeppingsprogram, soos RoboHelp, Help and Manual, Doc-To-Help, Flare, HelpLogix of HelpServer.
Wenke
- Die teks van die programdokumentasie moet so gestruktureer wees dat dit maklik leesbaar is. Plaas die prent so na as moontlik by die toepaslike teks. Verdeel die dokumentasie logies volgens afdelings en onderwerpe. Elke afdeling of onderwerp moet 'n spesifieke probleem beskryf, beide taak- en programkenmerke. Verwante kwessies kan verduidelik word met skakels of verwysingslyste.
- Elk van die dokumentasiehulpmiddels wat in hierdie artikel beskryf word, kan aangevul word deur 'n skermkiekieprogram, soos SnagIt as u dokumentasie verskeie skermkiekies benodig. Soos enige ander dokumentasie, moet u ook skermkiekies insluit om te verduidelik hoe die app werk, eerder as om die gebruiker te "lok".
- Dit is baie belangrik om aandag te gee aan styl, veral as u sagtewaredokumentasie vir eindgebruikers skryf. Spreek gebruikers aan met die voornaamwoord "jy", in plaas van "gebruiker".
