Dobra softverska dokumentacija, bilo da se radi o specifikacijskoj 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 korisniku potrebne. 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 podatke 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 stvara, 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 uporabe funkcije/potprograma, ulazne i izlazne vrijednosti.
- Programske varijable i konstante, te kako se koriste.
- Cjelokupna struktura programa. Za programe temeljene na pogonu možda ćete morati opisati svaki modul i knjižnicu. Ili, ako pišete priručnik za web-program, možda ćete morati objasniti koje datoteke koristi svaka stranica.
Korak 2. Odlučite koja bi razina dokumentacije trebala biti prisutna i odvojiva od programskog koda
Što je više tehničke dokumentacije uključeno u programski kod, to će je biti lakše 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 zapisati 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 vlastite 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 ne, upotrijebljeni alati ovisit će o potrebnoj dokumentaciji.
- Uređivač teksta kao što je Microsoft Word prikladan je za stvaranje tekstualnih datoteka dokumenata, sve dok je dokumentacija sažeta i jednostavna. Kako bi stvorili dugu dokumentaciju sa složenim tekstom, većina tehničkih pisaca odabire specijalizirani alat za dokumentaciju, poput Adobe FrameMakera.
- 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 razumjeti kako koristiti aplikaciju, postoji nekoliko drugih razloga koji mogu biti temelj stvaranja dokumentacije, poput pomoći marketing odjelu u prodaji aplikacije, poboljšanja imidža tvrtke 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 puno dokumentacije za rad, trebala bi biti osmišljena tako da bude intuitivnija
Korak 2. Upoznajte ciljnu publiku dokumentacije
Općenito, korisnici softvera imaju ograničeno znanje o računalima izvan aplikacija koje koriste. Postoji nekoliko načina za podmirivanje njihovih potreba za dokumentacijom:
- Obratite pozornost na naslov korisnika softvera. Na primjer, administrator sustava općenito razumije različite računalne aplikacije, dok tajnik poznaje samo aplikacije koje koristi za unos podataka.
- Obratite pozornost 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. Intervjuiranjem potencijalnih korisnika možete saznati je li vaša procjena naziva radnog mjesta točna.
- Obratite pozornost na postojeću dokumentaciju. Dokumentacija i specifikacije funkcionalnosti softvera mogu pokazati što 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 što je potrebno za dovršetak zadatka i što je potrebno prije nego što ga dovršite.
Korak 3. Odredite odgovarajući format dokumentacije
Softverska dokumentacija može se slagati u 1 ili 2 formata, naime referentne knjige i priručnike. Ponekad je kombiniranje dva formata dobro rješenje.
- Referentni formati koriste se za opisivanje svih softverskih značajki, kao što su gumbi, 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 zaslonu, korisnik će dobiti relevantnu temu.
- Ručni format služi za objašnjenje kako nešto učiniti sa softverom. Priručnici su općenito u tiskanom 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 kontekstualno osjetljivi, ali mogu biti povezani iz kontekstno 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 upakirana u jedan ili više sljedećih formata: tiskani priručnici, PDF datoteke, datoteke pomoći ili online pomoć. 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 također sadržavati demonstracijske videozapise, 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
Tiskani priručnici ili PDF -ovi mogu se stvoriti programom za obradu teksta kao što je Word ili naprednim uređivačem teksta poput FrameMakera, ovisno o duljini i složenosti datoteke. Datoteke pomoći mogu se pisati pomoću programa za izradu 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 na takav način da je lak za čitanje. Postavite sliku što je moguće bliže odgovarajućem tekstu. Logično raščlanite dokumentaciju po odjeljcima i temama. Svaki odjeljak ili tema trebaju opisati određeni problem, i zadatke i značajke programa. Povezana pitanja mogu se objasniti vezama ili popisima 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, osobito ako pišete softversku dokumentaciju za krajnje korisnike. Korisnicima se obratite zamjenicom "ti", umjesto "korisnik".
