Hoe om sagteware dokumentasie te skryf

Goeie dokumentasie sagteware, óf `n spesifikasie dokument vir programmeerders en testers, `n tegniese dokument vir interne gebruikers, of sagteware handleidings en hulp dokumente vir eindgebruikers, help die persoon om met die sagteware om sy funksies te verstaan en funksies. Goeie gebruikersdokumentasie is spesifiek, bondig en relevant en gee al die belangrike inligting aan die persoon wat die sagteware gebruik. Hier volg instruksies oor hoe om `n sagteware dokumentasie vir tegniese gebruikers en eindgebruikers te skryf.

conținut

Stappe
Metode 1skryf `n sagteware dokumentasie vir tegniese gebruikers
Metode 2skryf sagteware dokumentasie vir eindgebruikers
Wenke
Dinge wat jy nodig het

stappe

Metode 1
Skryf `n sagteware dokumentasie vir tegniese gebruikers

Prent getiteld Skryf sagteware dokumentasie Stap 1

Bepaal watter inligting ingesluit moet word. Die sagteware spesifikasie dokumente dien as verwysing handleidings vir ontwerpers van gebruikerskoppelvlak, programmeerders wat kode te skryf, en testers wat bevestig dat die sagteware werk as dit moet. Die presiese inligting hang af van die betrokke program, maar dit kan enige van die volgende dinge insluit:

Noodsaaklike lêers binne die aansoek. Dit kan die lêers bevat wat deur die ontwikkelingspan geskep is, die databasisse wat deur die bedryfsprogram verkry word, en derdeparty-nutsdienste.
Funksies en subroutines. Dit sluit in `n verduideliking van wat elke subroutine of funksie doen, insluitende die omvang van die insette en uitsetwaardes.
Veranderlikes en programkonstantes, en hoe dit in die aansoek gebruik word.
Die algemene struktuur van die program. Vir `n program wat op die hardeskyf werk, kan dit nodig wees om die individuele modules en biblioteke van die program te beskryf, terwyl dit vir `n internetprogram nodig mag wees om te beskryf watter bladsye watter lêers gebruik.

Prent getiteld Skryf sagteware dokumentasie Stap 2

Besluit hoeveel van die dokumentasie binne die programkode moet wees en hoeveel moet uitmekaar wees. Hoe meer jy die tegniese dokumentasie binne die bronkode van die program te ontwikkel, hoe makliker sal dit werk en tempo te handhaaf met die kode, en sal ook makliker wees om die verskillende weergawes van die oorspronklike aansoek te dokumenteer. Op `n minimum moet die dokumentasie in die bronkode die doel van die funksies, subroutines, veranderlikes en konstantes verduidelik.

As die bronkode baie lank is, kan dit gedokumenteer word in die vorm van `n hulplêer, wat geïndekseer kan word of soektogte met sleutelwoorde kan toelaat. Dit is veral voordelig vir toepassings waarin die logika van die program oor verskeie bladsye gefragmenteer word en sluit `n aantal komplementêre lêers in, soos by sekere internettoepassings.

Sommige programmeertale, soos Java en die .NET-raamwerk (Visual Basic.NET, C #), het hul eie reëls vir die dokumentasie van die kode. Volg in hierdie geval die reëls oor hoeveel van die dokumentasie by die bronkode ingesluit moet word.

Prent getiteld Skryf sagteware dokumentasie Stap 3

Kies die toepaslike dokumentasie instrument. Dit word in sekere mate bepaal deur die taal waarmee die kode geskryf word, of dit C ++, C #, Visual Basic, Java of PHP is, aangesien daar spesifieke gereedskap vir hierdie en ander tale is. In ander gevalle word die gereedskap wat gebruik word, bepaal afhangende van die tipe dokumentasie wat benodig word.

Woordverwerkers in Microsoft Word is geskik om tekslêers in die dokumentasie afsonderlik te skep, solank die dokumentasie redelik kort en eenvoudig is. Vir lang en komplekse teks lêers, verkies baie tegniese skrywers dokumentasie gereedskap soos Adobe FrameMaker.

Jy kan help lêers te skep om die bronkode gebruik van enige hulpmiddel om te help lêers te skep, as RoboHelp, Hulp en Handleiding, Doc-To-Help, dolleman Flare, of HelpLogix dokumenteer.

Metode 2
Skryf sagteware dokumentasie vir eindgebruikers

Prent getiteld Skryf sagteware dokumentasie Stap 4

Bepaal die kommersiële doeleindes van u dokumentasie. Terwyl die praktiese rede dat die sagteware is gedokumenteer is om gebruikers te help verstaan hoe om die aansoek te gebruik, daar is ook ander redes, soos die ondersteuning van die bemarking van sagteware, die verbetering van die beeld van die maatskappy, en die belangrikste, koste te verminder van tegniese ondersteuning. In sommige gevalle is dokumentasie nodig om aan sekere regulasies of wetlike vereistes te voldoen.

Sagteware dokumentasie moet egter nooit vergoed word vir swak koppelvlakontwerp nie. As `n aansoekskerm bladsye en bladsye dokumentasie benodig om dit te verduidelik, is dit beter om die ontwerp van die skerm te verander en iets meer intuïtief te doen.

Prent getiteld Skryf sagteware dokumentasie Stap 5

Verstaan wie jy die dokumentasie skryf. In die meeste gevalle weet sagtewaregebruikers min van rekenaars buite die take wat hulle toelaat om die programme wat hulle gebruik, uit te voer. Daar is verskeie maniere om te bepaal hoe om jou behoeftes te voorsien met dokumentasie.

Let op die professionele titels wat u potensiële gebruikers het. `N Stelseladministrateur kan `n kundige wees in verskeie rekenaarprogramme, terwyl `n werknemer wat data invoer, slegs die aansoek kan weet wat hy op daardie tydstip gebruik om die data in te voer.

Let op die gebruikers self. Alhoewel professionele titels gewoonlik aandui wat mense doen, kan daar aansienlike variasie wees in hoe sommige titels in sekere organisasies gebruik word. Deur ondervraging van potensiële gebruikers, kan jy `n idee kry of jy reg het oor wat jy dink hulle professionele titel aandui.

Let op die bestaande dokumentasie. Die dokumentasie van die vorige weergawes van die sagteware, sowel as die funksionele spesifikasies, gee `n paar aanduidings oor wat die gebruiker sal moet weet hoe om die program te gebruik. Hou egter in gedagte dat eindgebruikers nie belangstel in hoe die program werk nie, maar wat die program vir hulle kan doen.

Identifiseer die take wat nodig is om die werk te verrig, en watter take moet gedoen word voordat die ander take uitgevoer kan word.

Prent getiteld Skryf sagteware dokumentasie Stap 6

Bepaal die toepaslike formaat (of toepaslike formate) vir die dokumentasie. Die sagteware dokumentasie kan gestruktureer word in een van twee formate, die verwysingshandleiding en die gebruikersgids. Soms is die beste benadering om `n kombinasie van beide formate te gebruik.

`N Naslaanhandleiding is toegewyd aan die verduideliking van die individuele eienskappe van `n sagteware (knoppie, balk, veld en dialoogkassie) en hoe dit werk. Baie hulp lêers word geskryf met behulp van hierdie formaat, veral hulp lêers wat die konteks in ag neem en `n toepaslike onderwerp vertoon wanneer die gebruiker die Help-knoppie op `n spesifieke skerm klik.

`N Gebruikersgidsformaat verduidelik hoe die sagteware gebruik word om `n bepaalde taak uit te voer. Gebruikersgidse word gewoonlik gedruk of in PDF-formaat, hoewel sommige hulp lêers onderwerpe bevat oor hoe om spesifieke take te verrig (gewoonlik help hierdie hulponderwerpe nie die konteks nie, alhoewel hulle dalk aan ander gekoppel kan word vakke wat dit doen). In die algemeen kom die gebruikersgidse in die vorm van tutoriale, met `n opsomming van die taak wat in die inleiding gedoen moet word en die instruksies wat in genommerde stappe aangebied word.

Prent Titel Skryf Sagteware Dokumentasie Stap 7

Besluit watter vorm (of vorms) die dokumentasie moet neem. Sagteware dokumentasie vir eindgebruikers kan een van verskeie vorms gebruik: gedrukte handleidings, PDF-dokumente, hulp-lêers of aanlynhulp. Elkeen van die vorms is ontwerp om die gebruiker hoe om elke funksie van die program gebruik wys, óf as `n stap vir stap gids of tutorial- in die geval van hulp lêers en online help, kan dit sluit video demonstrasies behalwe die teks en die beelde.

Die aanlynhulp lêers moet geïndekseer word en soektogte met sleutelwoorde toelaat sodat die gebruiker vinnig die inligting kan kry wat hulle soek. Alhoewel die gereedskap om die hulp lêers te skep, outomaties die indekse kan genereer, is dit gewoonlik beter om dit handmatig te skep, met die terme waarna gebruikers waarskynlik sal soek.

Prent getiteld Skryf sagteware dokumentasie Stap 8

Kies die toepaslike dokumentasie instrument. Die gedrukte of PDF gebruikershandleidings kan geskryf word met `n woordverwerker soos Word of `n gesofistikeerde teksredakteur soos Frame Maker, afhangende van die lengte en kompleksiteit daarvan. Hulp lêers kan met behulp van gereedskap geskryf word om hulplêers te skep soos RoboHelp, Help en Handleiding, Doc-To-Help, Flare of HelpLogix.

wenke

Die teks moet so georganiseer word dat dit maklik kan lees, met die beelde so na as moontlik aan die teks geplaas wat na hulle verwys. Skei die dokumentasie in afdelings en onderwerpe op `n logiese wyse. Elke afdeling of onderwerp moet `n enkele probleem aanspreek, of dit nou `n enkele funksie of taak van die program is. Verwante onderwerpe kan aangespreek word deur gebruik te maak van "sien ook" lyste of hiperskakels, soos nodig.
Enige van die dokumentasie gereedskap wat hierbo genoem word, kan aangevul word met `n program wat u toelaat om skermkiekies te neem, soos Snagit, indien die dokumentasie sekere skermkiekies benodig. Soos met ander dokumentasie, moet opnames ingesluit word om te verduidelik hoe die program werk, om nie die gebruiker te verblind nie.
Toon is veral belangrik, veral wanneer sagteware dokumentasie vir eindgebruikers geskryf word. Noem die gebruiker met die tweede persoon "jy" in plaas van die derde persoon "die gebruikers" te gebruik.