Dobra dokumentacija o programski opremi, naj bo to specifikacija za programerje in preizkuševalce, tehnična dokumentacija za notranje uporabnike ali priročniki in datoteke pomoči za končne uporabnike, bo uporabnikom pomagala razumeti funkcije in funkcije programske opreme. Dobra dokumentacija je posebna, jasna in ustrezna dokumentacija z vsemi informacijami, ki jih potrebuje uporabnik. Ta članek vas bo vodil pri pisanju programske dokumentacije za tehnične uporabnike in končne uporabnike.
Korak
Metoda 1 od 2: Pisanje programske dokumentacije za tehnične uporabnike
Korak 1. Vedite, katere podatke vključiti
Dokument s specifikacijami se uporablja kot referenčni priročnik za oblikovalce vmesnikov, programerje, ki pišejo kodo, in preizkuševalce, ki preverjajo delovanje programske opreme. Podatki, ki jih je treba vključiti, so odvisni od programa, ki se ustvarja, lahko pa vključujejo naslednje:
- Pomembne datoteke v aplikaciji, na primer datoteke, ki jih je ustvarila razvojna skupina, baze podatkov, do katerih je dostopen med izvajanjem programa, in aplikacije drugih proizvajalcev.
- Funkcije in podprogrami, vključno z razlago uporabe funkcije/podprograma, vhodnimi in izhodnimi vrednostmi.
- Programske spremenljivke in konstante ter kako se uporabljajo.
- Celotna struktura programa. Za programe, ki temeljijo na pogonih, boste morda morali opisati vsak modul in knjižnico. Ali pa, če pišete priročnik za spletni program, boste morda morali pojasniti, katere datoteke uporablja vsaka stran.
2. korak Odločite se, kakšna raven dokumentacije mora biti prisotna in ločena od programske kode
Bolj ko bo tehnična dokumentacija vključena v programsko kodo, lažje jo boste posodabljali in vzdrževali ter razlagali različne različice programa. Vsaj dokumentacija v programski kodi mora vključevati uporabo funkcij, podprogramov, spremenljivk in konstant.
- Če je vaša izvorna koda dolga, lahko v datoteko za pomoč napišete dokumentacijo, ki jo lahko nato indeksirate ali iščete z določenimi ključnimi besedami. Ločene datoteke dokumentacije so uporabne, če je programska logika razdeljena na več strani in vključuje podporne datoteke, na primer spletno aplikacijo.
- Nekateri programski jeziki (na primer Java, Visual Basic. NET ali C#) imajo svoje standarde dokumentacije kod. V takih primerih upoštevajte standardno dokumentacijo, ki mora biti vključena v izvorno kodo.
Korak 3. Izberite ustrezno orodje za dokumentacijo
V nekaterih primerih je orodje za dokumentacijo določeno z uporabljenim programskim jezikom. Jeziki C ++, C#, Visual Basic, Java, PHP in drugi imajo svoja orodja za dokumentacijo. Če pa ne, bodo uporabljena orodja odvisna od zahtevane dokumentacije.
- Urejevalnik besedil, kot je Microsoft Word, je primeren za ustvarjanje besedilnih datotek dokumentov, če je dokumentacija jedrnata in preprosta. Za ustvarjanje dolge dokumentacije s kompleksnim besedilom večina tehničnih piscev izbere specializirano orodje za dokumentacijo, na primer Adobe FrameMaker.
- Datoteke za pomoč pri dokumentiranju izvorne kode lahko ustvarite s programom za ustvarjanje podpornih datotek, kot so RoboHelp, Help and Manual, Doc-To-Help, MadCap Flare ali HelpLogix.
Metoda 2 od 2: Pisanje programske dokumentacije za končne uporabnike
Korak 1. Spoznajte poslovne razloge za nastanek priročnika
Medtem ko je glavni razlog za dokumentacijo programske opreme, da uporabnikom pomaga razumeti, kako uporabljati aplikacijo, obstaja več drugih razlogov, na katerih temelji ustvarjanje dokumentacije, na primer pomoč oddelku za trženje pri prodaji aplikacije, izboljšanje podobe podjetja in zmanjšanje tehnične podpore. stroški. V nekaterih primerih je potrebna dokumentacija v skladu s predpisi ali drugimi zakonskimi zahtevami.
Vendar dokumentacija ni dober nadomestek za vmesnik. Če aplikacija za delovanje potrebuje veliko dokumentacije, bi morala biti zasnovana tako, da je bolj intuitivna
Korak 2. Poznajte ciljno publiko dokumentacije
Na splošno imajo uporabniki programske opreme omejeno računalniško znanje, razen aplikacij, ki jih uporabljajo. Potrebe po dokumentaciji lahko izpolnite na več načinov:
- Bodite pozorni na naslov uporabnika programske opreme. Skrbnik sistema na primer na splošno razume različne računalniške aplikacije, tajnik pa pozna le aplikacije, ki jih uporablja za vnos podatkov.
- Bodite pozorni na uporabnike programske opreme. Čeprav so njihovi položaji na splošno združljivi z opravljenimi nalogami, imajo lahko ti položaji različne obremenitve, odvisno od kraja poslovanja. Z anketiranjem potencialnih uporabnikov lahko ugotovite, ali je vaša ocena naziva delovnega mesta pravilna.
- Bodite pozorni na obstoječo dokumentacijo. Dokumentacija in specifikacije funkcionalnosti programske opreme lahko pokažejo, kaj morajo uporabniki vedeti, da jih lahko uporabljajo. Vendar ne pozabite, da uporabnike morda ne zanima poznavanje "notranjosti" programa.
- Vedite, kaj je potrebno za dokončanje naloge in kaj je potrebno, preden jo lahko dokončate.
Korak 3. Določite ustrezno obliko dokumentacije
Programsko dokumentacijo lahko uredite v 1 ali 2 oblikah, in sicer v referenčnih knjigah in priročnikih. Včasih je kombinacija dveh formatov dobra rešitev.
- Referenčni formati se uporabljajo za opis vseh funkcij programske opreme, kot so gumbi, zavihki, polja in pogovorna okna, ter njihovo delovanje. Nekatere datoteke pomoči so napisane v tej obliki, zlasti tiste, ki so odvisne od konteksta. Ko uporabnik na določenem zaslonu klikne Pomoč, bo prejel ustrezno temo.
- Ročna oblika se uporablja za razlago, kako nekaj storiti s programsko opremo. Navodila so običajno v tiskani ali PDF obliki, čeprav nekatere strani s pomočjo vsebujejo tudi navodila, kako narediti določene stvari. (Na splošno ročne oblike niso kontekstno občutljive, lahko pa so povezane s kontekstno občutljivimi temami). Priročniki so na splošno v obliki vodnika s povzetkom nalog, ki jih je treba opraviti, v opisu in vodilom, oblikovanim po korakih.
Korak 4. Odločite se za vrsto dokumentacije
Dokumentacija programske opreme za uporabnike je lahko pakirana v enem ali več naslednjih oblikah: tiskani priročniki, datoteke PDF, datoteke pomoči ali spletna pomoč. Vsaka vrsta dokumentacije je zasnovana tako, da vam pokaže, kako uporabljati funkcije programske opreme, pa naj gre za priročnik ali vadnico. Spletna dokumentacija in strani s pomočjo lahko vključujejo tudi predstavitvene videoposnetke, besedilo in statične slike.
Spletne datoteke pomoči in podpore je treba indeksirati in iskati z uporabo ključnih besed, tako da lahko uporabniki hitro najdejo potrebne informacije. Čeprav lahko aplikacija za ustvarjanje datotek pomoči samodejno ustvari kazalo, je še vedno priporočljivo, da indeks ustvarite ročno z uporabo pogosto iskanih ključnih besed
Korak 5. Izberite ustrezno orodje za dokumentacijo
Tiskane priročnike ali datoteke PDF lahko ustvarite s programom za urejanje besedil, kot je Word, ali naprednim urejevalnikom besedil, kot je FrameMaker, odvisno od dolžine in zahtevnosti datoteke. Datoteke za pomoč lahko zapišete s programom za ustvarjanje datotek pomoči, kot so RoboHelp, Help and Manual, Doc-To-Help, Flare, HelpLogix ali HelpServer.
Nasveti
- Besedilo programske dokumentacije mora biti strukturirano tako, da je lahko berljivo. Sliko postavite čim bližje ustreznemu besedilu. Logično razčlenite dokumentacijo po oddelkih in temah. Vsak razdelek ali tema mora opisati določeno težavo, tako naloge kot funkcije programa. Sorodna vprašanja je mogoče razložiti s povezavami ali referenčnimi seznami.
- Vsako orodje za dokumentacijo, opisano v tem članku, lahko dopolni program za ustvarjanje posnetkov zaslona, na primer SnagIt, če vaša dokumentacija zahteva več posnetkov zaslona. Kot vsaka druga dokumentacija bi morali vključiti tudi posnetke zaslona, ki vam pomagajo razložiti, kako aplikacija deluje, in ne "zvabiti" uporabnika.
- Pozornost na slog je zelo pomembna, še posebej, če pišete dokumentacijo o programski opremi za končne uporabnike. Uporabnike nagovorite z zaimkom »vi« namesto »uporabnik«.
