Dobra softverska dokumentacija, bilo da se radi o dokumentaciji za programere i testere, tehničkoj dokumentaciji za interne korisnike ili priručnicima i datotekama pomoći za krajnje korisnike, pomoći će korisnicima da razumiju značajke i funkcije softvera. Dobra dokumentacija je dokumentacija koja je specifična, jasna i relevantna, sa svim informacijama koje su potrebne korisniku. Ovaj članak će vas uputiti u pisanje softverske dokumentacije za tehničke korisnike i krajnje korisnike.
Korak
Metoda 1 od 2: Pisanje softverske dokumentacije za tehničke korisnike
Korak 1. Znajte koje informacije uključiti
Dokument sa specifikacijama koristi se kao referentni priručnik za dizajnere sučelja, programere koji pišu kod i testere koji provjeravaju performanse softvera. Podaci koje je potrebno uključiti ovisit će o programu koji se kreira, ali mogu uključivati sljedeće:
- Važne datoteke u aplikaciji, kao što su datoteke koje je stvorio razvojni tim, baze podataka kojima se pristupa dok je program pokrenut i aplikacije trećih strana.
- Funkcije i potprogrami, uključujući objašnjenje upotrebe funkcije/potprograma, ulazne i izlazne vrijednosti.
- Programske varijable i konstante, te kako se koriste.
- Sveukupna programska struktura. Za programe zasnovane na pogonima možda ćete morati opisati svaki modul i biblioteku. Ili, ako pišete priručnik za program zasnovan na webu, možda ćete morati objasniti koje datoteke koristi svaka stranica.
Korak 2. Odlučite koji nivo dokumentacije treba da bude prisutan i odvojiv od programskog koda
Što je više programske dokumentacije uključeno u programski kod, lakše će je biti ažurirati i održavati, kao i objasniti različite verzije programa. Najmanje, dokumentacija u programskom kodu trebala bi uključivati upotrebu funkcija, potprograma, varijabli i konstanti.
- Ako je vaš izvorni kod dugačak, možete napisati dokumentaciju u datoteku pomoći, koja se zatim može indeksirati ili pretraživati pomoću određenih ključnih riječi. Odvojene datoteke dokumentacije korisne su ako je programska logika podijeljena na nekoliko stranica i uključuje datoteke podrške, poput web aplikacije.
- Neki programski jezici (kao što su Java, Visual Basic. NET ili C#) imaju svoje standarde dokumentacije koda. U takvim slučajevima slijedite standardnu dokumentaciju koja mora biti uključena u izvorni kod.
Korak 3. Odaberite odgovarajući alat za dokumentaciju
U nekim slučajevima, alat za dokumentaciju određen je programskim jezikom koji se koristi. Jezici C ++, C#, Visual Basic, Java, PHP i drugi imaju svoje alate za dokumentaciju. Međutim, ako nije, korišteni alati ovisit će o potrebnoj dokumentaciji.
- Uređivač teksta kao što je Microsoft Word prikladan je za kreiranje tekstualnih datoteka dokumenta, sve dok je dokumentacija sažeta i jednostavna. Da bi stvorili dugu dokumentaciju sa složenim tekstom, većina tehničkih pisaca bira specijalizirani alat za dokumentaciju, kao što je Adobe FrameMaker.
- Datoteke pomoći za dokumentiranje izvornog koda mogu se stvoriti pomoću programa za generiranje datoteka podrške, kao što su RoboHelp, Pomoć i priručnik, Doc-To-Help, MadCap Flare ili HelpLogix.
Metoda 2 od 2: Pisanje softverske dokumentacije za krajnje korisnike
Korak 1. Upoznajte poslovne razloge na kojima se temelji priručnik
Iako je glavni razlog za softversku dokumentaciju pomoći korisnicima da razumiju kako koristiti aplikaciju, postoji nekoliko drugih razloga koji mogu biti u osnovi stvaranja dokumentacije, poput pomoći marketing odjelu u prodaji aplikacije, poboljšanja imidža kompanije i smanjenja tehničke podrške troškovi. U nekim slučajevima potrebna je dokumentacija u skladu s propisima ili drugim zakonskim zahtjevima.
Međutim, dokumentacija nije dobra zamjena za sučelje. Ako aplikacija zahtijeva mnogo dokumentacije za rad, trebala bi biti dizajnirana tako da bude intuitivnija
Korak 2. Upoznajte ciljnu publiku dokumentacije
Općenito, korisnici softvera imaju ograničeno znanje o računaru izvan aplikacija koje koriste. Postoji nekoliko načina za podmirivanje njihovih potreba za dokumentacijom:
- Obratite pažnju na naslov korisnika softvera. Na primjer, administrator sistema općenito razumije različite računarske aplikacije, dok sekretar poznaje samo aplikacije koje koristi za unos podataka.
- Obratite pažnju na korisnike softvera. Iako su njihova radna mjesta općenito kompatibilna s izvršenim zadacima, ti položaji mogu imati različito opterećenje, ovisno o mjestu poslovanja. Razgovaranjem s potencijalnim korisnicima možete saznati je li vaša procjena naziva radnog mjesta točna.
- Obratite pažnju na postojeću dokumentaciju. Dokumentacija i specifikacije funkcionalnosti softvera mogu pokazati šta korisnici trebaju znati da bi ih mogli koristiti. Međutim, imajte na umu da korisnike možda neće zanimati poznavanje "unutrašnjosti" programa.
- Znajte šta je potrebno za dovršetak zadatka i šta je potrebno prije nego što ga dovršite.
Korak 3. Odredite odgovarajući format dokumentacije
Softverska dokumentacija može biti raspoređena u 1 ili 2 formata, naime referentne knjige i priručnici. Ponekad je kombiniranje dva formata dobro rješenje.
- Referentni formati koriste se za opisivanje svih softverskih funkcija, kao što su dugmad, kartice, polja i dijaloški okviri, te kako oni rade. Neke datoteke pomoći napisane su u ovom formatu, posebno one koje su osjetljive na kontekst. Kada korisnik klikne Pomoć na određenom ekranu, korisnik će dobiti relevantnu temu.
- Ručni format se koristi za objašnjenje kako nešto učiniti sa softverom. Priručnici su općenito u štampanom ili PDF formatu, iako neke stranice za pomoć sadrže i upute o tome kako učiniti određene stvari. (Općenito, ručni formati nisu osjetljivi na kontekst, ali mogu biti povezani iz kontekstualno osjetljivih tema). Priručnici su općenito u obliku vodiča, sa sažetkom zadataka koje treba obaviti u opisu i vodičem oblikovanim u koracima.
Korak 4. Odlučite se o vrsti dokumentacije
Softverska dokumentacija za korisnike može biti upakovana u jedan ili više sljedećih formata: štampani priručnici, PDF datoteke, datoteke pomoći ili pomoć na mreži. Svaka vrsta dokumentacije osmišljena je tako da vam pokaže kako koristiti funkcije softvera, bilo da se radi o vodiču ili vodiču. Mrežna dokumentacija i stranice za pomoć mogu uključivati demonstracijske video zapise, tekst i statične slike.
Mrežne datoteke pomoći i podrške treba indeksirati i pretraživati pomoću ključnih riječi kako bi korisnici mogli brzo pronaći potrebne informacije. Iako aplikacija za generiranje datoteka pomoći može automatski stvoriti indeks, ipak se preporučuje da indeks stvorite ručno koristeći često pretraživane ključne riječi
Korak 5. Odaberite odgovarajući alat za dokumentaciju
Odštampani priručnici ili PDF -ovi mogu se kreirati pomoću programa za obradu teksta kao što je Word ili naprednog uređivača teksta, poput FrameMakera, ovisno o dužini i složenosti datoteke. Datoteke pomoći mogu se pisati pomoću programa za stvaranje datoteka pomoći, kao što su RoboHelp, Pomoć i priručnik, Doc-To-Help, Flare, HelpLogix ili HelpServer.
Savjeti
- Tekst programske dokumentacije treba biti strukturiran tako da bude lak za čitanje. Postavite sliku što je moguće bliže odgovarajućem tekstu. Logično razložite dokumentaciju po odjeljcima i temama. Svaki odjeljak ili tema trebaju opisati određeni problem, i zadatke i značajke programa. Srodna pitanja mogu se objasniti vezama ili listama referenci.
- Svaki od alata za dokumentaciju opisanih u ovom članku može se nadopuniti programom za izradu snimaka zaslona, poput SnagIta ako vaša dokumentacija zahtijeva više snimaka zaslona. Kao i svaka druga dokumentacija, trebali biste uključiti i snimke zaslona kako biste objasnili kako aplikacija radi, a ne "namamiti" korisnika.
- Obraćanje pažnje na stil vrlo je važno, posebno ako pišete softversku dokumentaciju za krajnje korisnike. Obratite se korisnicima zamjenicom "ti", umjesto "korisnik".
