Sadržaj

• koraci
• Savjet
• Potrebni materijali

Dobra softverska dokumentacija - bilo za programere i testere, za tehničke dokumente za interne korisnike ili za softverske priručnike i datoteke za pomoć krajnjim korisnicima - pomaže osobi koja radi s softverom da razumije njegove funkcije i karakteristike. Dobra dokumentacija je specifična, sažetka i relevantna te pruža sve važne informacije osobama koje koriste program. Pročitajte upute za pisanje softverske dokumentacije za tehničke i krajnje korisnike.

koraci

Metoda 1 od 2: Pisanje softverske dokumentacije za tehničke korisnike

1. 

   Odredite koje informacije treba uključiti. Dokumenti sa specifikacijom softvera služe kao referentni priručnici za dizajnere korisničkog sučelja, programere koji pišu kod i testere koji provjeravaju da softver radi po želji. Točne informacije ovise o predmetnom programu, ali mogu uključivati:
   • Ključne datoteke unutar aplikacije. Mogu uključiti datoteke koje je stvorio razvojni tim, baze podataka kojima je pristupio tijekom rada programa i uslužne programe treće strane.
   • Funkcije i podprogrami. Ovdje je uključeno objašnjenje o tome što svaka funkcija ili podprogram radi, uključujući raspon ulaznih i izlaznih vrijednosti.
   • Programske varijable i konstante i kako se koriste u aplikaciji.
   • Opća struktura programa. Za aplikaciju koja se temelji na disku to može značiti opis pojedinih modula i knjižnica programa, dok za web aplikaciju, koje stranice koriste koje datoteke.

2. 

   
   
   Odlučite koliki dio dokumentacije treba biti unutar programskog koda i koliko treba biti odvojen od nje. Što je više tehničke dokumentacije razvijene u programskom izvoru, lakše ćete ažurirati i održavati kôd, kao i dokumentirati različite verzije izvorne aplikacije. U najmanju ruku, dokumentacija u izvornom kodu trebala bi objasniti svrhu funkcija, podprograma, varijabli i konstanta.
   • Ako je izvorni kod posebno dugačak, može se dokumentirati u obliku datoteke pomoći koja se može indeksirati ili pretraživati ​​ključnim riječima. To je posebna prednost za aplikacije u kojima je programska logika fragmentirana na više stranica i uključuje nekoliko dodatnih datoteka, kao i za određene web aplikacije.
   • Neki programski jezici, kao što su Java i .NET Framework (Visual Basic .NET, C #), imaju svoje programe za dokumentiranje koda. U takvim slučajevima slijedite norme za količinu dokumentacije koju treba uključiti.

3. 

   
   
   Odaberite pravi alat za dokumentaciju. U određenoj mjeri to će se odrediti jezikom na kojem je kod napisan, bilo u C ++, C #, Visual Basic, Java ili PHP-u, jer postoje specifični alati za ove i druge jezike. U ostalim se slučajevima alat koji se koristi određuje prema vrsti potrebne dokumentacije.
   • Programi za obradu teksta za Microsoft Word prikladni su za stvaranje zasebnih tekstualnih datoteka, sve dok je dokumentacija relativno kratka i jednostavna. Za duge i složene tekstualne datoteke, mnogi tehnički pisci preferiraju alat za dokumentaciju, kao što je Adobe FrameMaker.
   • Datoteke pomoći za dokumentiranje izvornog koda mogu se proizvesti s bilo kojim alatom za pomoć u tehničkom pisanju, kao što su RoboHelp, Help and Manual, Doc-To-Help, MadCap Flare ili HelpLogix.

Metoda 2 od 2: Pisanje softverske dokumentacije za krajnje korisnike

1. 

   
   
   Odredite poslovne svrhe dokumentacije. Iako je funkcionalni razlog pomoći korisnicima da razumiju kako koristiti aplikaciju, postoje i drugi razlozi, poput pomoći u oglašavanju programa, poboljšanju imidža tvrtke i, što je najvažnije, smanjenju troškova tehničke podrške. U nekim je slučajevima potrebna dokumentacija da bi bila usklađena s određenim propisima ili drugim zakonskim zahtjevima.
   • Ni pod kojim uvjetima dokumentacija ne bi trebala zamijeniti loš dizajn sučelja. Ako zaslon aplikacija zahtijeva stranice i stranice dokumentacije kako bi ga objasnio, najbolje je promijeniti dizajn kako bi bio što intuitivniji.

2. 

   Shvatite publiku za koju pišete dokumentaciju. Korisnici softvera u većini slučajeva imaju malo znanja o računalima izvan zadataka aplikacija koje koriste. Postoji nekoliko načina kako odrediti kako udovoljiti svojim potrebama s vašom dokumentacijom.
   • Imajte na umu imena poslova potencijalnih korisnika. Administrator sustava vjerojatno će biti spretan u različitim softverskim aplikacijama, dok radnik za unos podataka vjerojatno poznaje samo onu aplikaciju koju koristi za unos podataka.
   • Promatrajte sami korisnike. Iako naslovi zaposlenika često ukazuju na ono što ljudi rade, može postojati velika razlika u načinu na koji se određeni nazivi koriste u određenoj organizaciji. Intervjuirajući potencijalne korisnike, možete saznati jesu li vaši dojmovi o vašim potrebama točni ili ne.
   • Pridržavajte se postojeće dokumentacije. Dokumentacija prethodnih verzija softvera, kao i funkcionalne specifikacije, daju neke naznake što će korisnik trebati znati za korištenje programa. Imajte na umu, međutim, da krajnje korisnike ne zanima kako program radi, već u tome što on može učiniti za njih.
   • Identificirajte zadatke potrebne za posao i one koje je potrebno obaviti prije njih.

3. 

   Odredite odgovarajuće formate za dokumentaciju. Dokumentacija softvera može biti strukturirana u 1 ili 2 formata, referentni priručnik i korisnički vodič. Ponekad je kombinacija formata najbolji pristup.
   • Format referentnog priručnika posvećen je objašnjavanju pojedinačnih karakteristika aplikacije (gumbi, kartice, polja i dijalozi) i njihovom radu. Mnoge datoteke pomoći napisane su u ovom formatu, koji prikazuje relevantnu temu svaki put kada korisnik klikne gumb pomoći na određenom zaslonu.
   • Format korisničkog vodiča objašnjava kako program koristiti za obavljanje određenog zadatka. Ovi vodiči obično se ispisuju ili prikazuju gotovo u PDF-ovima, iako neke datoteke pomoći uključuju teme o izvođenju određenih zadataka (ove teme pomoći uglavnom nisu kontekstualno osjetljive, iako mogu sadržavati veze na teme koje jesu). Korisnički vodiči obično imaju oblik udžbenika, sa sažetkom zadataka koji će se obavljati u uvodu i uputama navedenim u brojevima.

4. 

   Odlučite koji oblik dokumentacije treba poprimiti. Dokumentacija softvera za krajnje korisnike može imati jedan od nekoliko ili više oblika: tiskani priručnici, PDF dokumenti, datoteke pomoći ili internetska pomoć. Svaki je obrazac dizajniran tako da korisniku pokaže kako koristi svaku funkciju programa, bilo u obliku vodiča ili vodiča; u slučaju datoteka pomoći i mrežne pomoći, možete uključiti demo videozapise, kao i tekst i slike.
   • Datoteke pomoći moraju se indeksirati i pretraživati ​​po ključnim riječima kako bi korisnici brzo pronašli informacije koje žele. Iako alati za pisanje mogu generirati indekse automatski, najbolje je to učiniti ručno, koristeći uvjete koje korisnici vjerojatno traže.

5. 

   Odaberite odgovarajući alat za dokumentaciju. Tiskani ili PDF priručnici mogu se pisati programom za obradu teksta poput Word-a ili sofisticiranim uređivačem teksta poput FrameMaker-a, ovisno o njihovoj veličini i složenosti. Datoteke pomoći mogu se pisati pomoću određenog alata za datoteke pomoći, kao što su RoboHelp, Help and Manual, Doc-To-Help, Flare, HelpLogix ili HelpServer.

Savjet

• Tekst treba organizirati za lako čitanje, s tim da slike budu smještene u neposrednoj blizini teksta. Logično podijelite dokumentaciju na odjeljke i teme. Svaki se odjeljak ili tema prema potrebi može uputiti poveznicom "vidi također".
• Navedeni alati za dokumentaciju mogu se nadopuniti programom za stvaranje zaslona, ​​poput Snagita, ako dokumentacija zahtijeva više snimaka zaslona. Kao i u drugoj dokumentaciji, i ove bi trebao biti uključen kako bi se objasnio način na koji program radi, a da se ne impresionira korisnik.
• Ton je osobito važan, posebno pri pisanju dokumentacije za krajnje korisnike. Nazovite ih "vi" umjesto "korisnici".

Potrebni materijali

• Alat za dokumentaciju softvera / datoteke pomoći
• Alat za stvaranje zaslona