Kako pisati softversku dokumentaciju: 8 koraka

Dobra softverska dokumentacija - da li je to dokument koji sadrži specifikaciju zahtjeva za programere ili testere, tehnički dokument za interne korisnike, priručnik za korištenje softvera ili programskih upita za korisnike - pomaže u osobi koja radi sa softverom, razumije njegove karakteristične karakteristike i Funkcije. Slijedite savjete - kako pisati softversku dokumentaciju za tehničke i krajnje korisnike.

Korake

Metoda 1 od 2:

Pisanje softverske dokumentacije za tehničke korisnike.

jedan. Odrediti koje informacije moraju biti spomenute. Dokumenti o softverskim zahtevima služe kao referentni priručnik za dizajnere korisnika interfejsa, programeri koji pišu kod i testere koji provjeravaju da li softver funkcionira na sljedeći način. Točne informacije ovise o samom programu, međutim, može uključivati sljedeće:

Ključne datoteke u aplikaciji. To mogu biti datoteke koje je kreirao tim za programere, baze podataka uzrokovane tokom rada softvera i programi treće strane.
Funkcije i podprogrami. Ovdje je naznačeno da svaka funkcija i podprogram čini, uključujući ulazne i izlazne vrijednosti.
Softverske varijable i konstanta i kako se koriste u aplikaciji.
Opća struktura programa. Za aplikacije zasnovane na diskovima, vjerovatno će vam trebati opis pojedinačnih blokova i biblioteka programa, dok će web aplikacije trebati opis stranica koje koriste datoteke.

Slika pod nazivom Napišite softversku dokumentaciju Korak 2

2. Odlučite koliko dokumentacije treba biti u programskom kodu i koliko treba razdvojiti. Što se više tehnička dokumentacija kreira u programskom kodu, što će lakše ažurirati ovaj kod kao dokumentaciju koja se odnosi na različite verzije izvorne aplikacije. Na minimum, dokumentacija u programskom kodu treba objasniti funkcije, podprograme, softverske konstante i varijable.

Ako je programski kôd prilično dugačak, može se postaviti kao referentna datoteka u kojoj možete pretraživati po ključnim riječima ili putokazivima. To će biti veliki plus za aplikacije u kojima je programska logika podijeljena na mnoge stranice i uključuje pomoćne brojeve datoteka, kao u određenim web aplikacijama.

Neki programski jezici, kao što su Java ili Net okvir (vizualni osnovni.Net, C #), imaju vlastite standarde za kodeks dokumentacije. U takvim slučajevima slijedite standardna uputstva - koliko dokumentacije treba biti uključeno u programski kod.

Slika pod nazivom Napišite softversku dokumentaciju Korak 3

3. Odaberite odgovarajući alat. U određenoj mjeri je to definirano jezikom na kojem je kod napisana, biti C ++, C #, Visual Basic, Java ili PHP - za svaki su namijenjeni vlastiti alat. U drugim slučajevima, korišteni alat određuje se vrstom potrebne dokumentacije.

Tekst Editor "Microsoft Word" -Cercing alat za kreiranje odvojenih dokumentacije za tekstualne datoteke koja će biti jednostavna i kratka. Za duge tekstualne datoteke, mnogi programeri tehničke dokumentacije radije odabiru program Adobe Framemaker.

Tip datoteke za dokumentaciju softverskog koda mogu se napisati pomoću bilo kojeg alata, poput Robohelp, Help i Ručno, doc-za-pomoć, madcap flare ili "Helplogix".

Metoda 2 od 2:

Pisanje softverske dokumentacije za krajnje korisnike

jedan. Identificirajte komercijalna razmatranja za vašu dokumentaciju. Iako su funkcionalni razlozi za softversku dokumentaciju da pomognu korisnicima kako da koriste aplikaciju, postoje i drugi razlozi, poput pomoći u promociji robe na tržištu, poboljšavajući imidž kompanije i najvažnije, smanjenje troškova tehničke podrške. U određenim slučajevima, potrebna je dokumentacija za pridržavanje određenih pravila i zakonskih zahtjeva.

Ni u kojem slučaju, programska dokumentacija ne smije zamijeniti loš dizajn sučelja. Ako zaslon aplikacija zahtijeva puno objašnjenja, bolje je promijeniti dizajn na nešto intuitivnije.

Slika pod nazivom Napišite softversku dokumentaciju Korak 5

2. Shvatite publiku za koju pišete dokumentaciju. U većini slučajeva korisnici softvera malo znaju o računarima pored zadataka aplikacija. Postoji nekoliko načina da se utvrdi kako koordinirati njihove potrebe s dokumentacijom.

Pogledajte profesije u vlasništvu vaših potencijalnih korisnika. Administrator sustava vjerovatno će biti stručnjak za upotrebu softverskih aplikacija, dok operater unosa podataka vjerovatno posjeduje aplikaciju koju ili trenutno koristi za unos podataka.

Pogledajte same korisnike. Iako njihovi postovi uglavnom određuju ono što se ljudi bave, ali postoje značajne razlike u tome kako se u ovoj organizaciji koriste određene položaje. Provođenje intervjua sa potencijalnim korisnicima, možete dodati svoje mišljenje - Da li je ime post ispunio dužnosti.

Pogledajte postojeću dokumentaciju. Dokumentacija za prethodne verzije softvera daje približan koncept koji korisnik mora znati o korištenju programa. Međutim, sjetite se da krajnji korisnici ne zanimaju kako program funkcionira, važno je da oni znaju šta mogu učiniti s tim.

Odredite zadatke koji su neophodni za ovaj rad i koji zadaci moraju biti izvedeni prije nego što se mogu izvršiti ovi zadaci.

Slika pod nazivom Napisana softverska dokumentacija Korak 6

3. Odredite odgovarajući format (e) dokumentacije. Softverska dokumentacija može se strukturirati u jednom od dva formata - referentni vodič i uputstva za upotrebu. Ponekad je bolje odabrati mješovitu verziju ova dva formata.

Referentni vodič dizajniran je za objašnjenje alata softvera (tasteri, tablice, polje i dijaloški panel) i kako ovaj alat funkcionira. Mnoge brze datoteke napisane su u ovom formatu, a kontekstni zahtjevi pomažu pokazati željenu temu nakon što korisnik klikne na gumb "Pomoć" na željenom ekranu.

Upute za upotrebu objašnjava kako koristiti softver za izvedbu određenog zadatka. Uputstvo za upotrebu često ima štampani vodič ili PDF format, mada neki upita uključuju teme o tome kako izvesti određeni zadatak. (Ove referentne teme obično nisu kontekstualne, iako mogu biti hiperveze) Uputstvo za upotrebu često ima oblik referentne knjige s opisom zadatka i po korak po korak.

Slika pod nazivom Napišite softversku dokumentaciju Korak 7

4. Odlučite koji format (formati) dokumentacije treba biti. Softverska dokumentacija za krajnje korisnike može biti jedan ili više formata: Print Guide, Dokumenti u PDF formatu, Tip datoteke ili mrežnu pomoć. Svaki od ovih formata kreira se da bi pokazao korisnik kako koristiti svaku funkciju programa - biti kratak pregled ili vodič. Kao u slučaju brze datoteke i mrežne pomoći, dokumentacija može imati demonstrativni video ili tekst sa slikama.

Savjeti i datoteke pomoći putem interneta moraju imati pokazivače, pretraživanje po ključnim riječima, što će korisniku omogućiti brzo pronalaženje potrebnih informacija. Iako alati za brze datoteke mogu automatski kreirati pokazivače, bolje je to ručno učiniti koristeći izraze koje će korisnici najvjerovatnije postati pretrage.

Slika pod nazivom Napišite softversku dokumentaciju Korak 8

pet. Odaberite odgovarajući alat za kreiranje dokumentacije. Vodiči za ispis ili PDF format mogu se napisati u urednicima teksta kao što su "Word" ili "Framemaker", ovisno o dužini i složenosti priručnika. Tip datoteke mogu se pisati pomoću takvih razvojnih alata poput "Robohelp", "Pomoć i ručni", "Doc-to-Help", "Flare", "Helplogix" ili "Helplogix" ili "Helplogix".

Savjeti

Tekst bi trebao biti jednostavan za čitanje, slike bi trebale biti smještene što bliže tekstu kojem pripadaju. Gurnite dokumentaciju za odjeljke i logičke teme. Svaki se odjeljak ili tema treba da se tiču određenog pitanja, bilo da je to jedan program ili zadatak. Povezana pitanja treba navesti "za gledanje i" sa hipervezom, ako je potrebno.
Svi alati za kreiranje dokumentacije koji su gore navedeni mogu se nadopuniti programom zaslona zaslona, poput Snagita, ako dokumentacija zahtijeva određeni broj snimka zaslona. Kao i kod druge dokumentacije, snimke zaslona trebaju objasniti kako softver funkcionira, a ne zabludu korisnika.
Također je važno i ton pisanja dokumentacije, posebno ako je napisana za krajnje korisnike. Koristite drugo lice "vi", umjesto treće strane "korisnici".

Sta ti treba

Alat za pisanje dokumentacije / debule
Alat za stvaranje snimka zaslona