Cum se scrie documentația software

software-o bună documentare, fie un document de specificație pentru programatori și testeri, un document tehnic pentru utilizatorii interni sau manuale de software și documente de ajutor pentru utilizatorii finali, ajută persoana care lucrează cu software-ul pentru a înțelege caracteristicile sale și funcții. O documentație utilizator bună este specifică, concis, și relevante și furnizează toate informațiile importante pentru persoana care utilizează software-ul. Mai jos sunt instrucțiuni despre cum să scrieți o documentație software pentru utilizatorii tehnici și utilizatorii finali.

conținut

Pași
Metoda 1scrieți o documentație software pentru utilizatorii tehnici
Metoda 2scrieți documentația software pentru utilizatorii finali
Sfaturi
Lucruri de care ai nevoie

pași

Metoda 1
Scrieți o documentație software pentru utilizatorii tehnici

Imaginea intitulată Scrieți documentația software-ului Pasul 1

Stabilește ce informații trebuie incluse. Documentele cu specificații software servesc drept manuale de referință pentru designerii interfeței utilizator, programatorii care scriu codul și cei care verifică dacă software-ul funcționează corect. Informațiile exacte depind de programul în cauză, dar pot include oricare dintre următoarele lucruri:

Fișierele esențiale din cadrul aplicației. Acestea pot include fișierele create de echipa de dezvoltatori, bazele de date accesate de programul de operare și utilitățile terților.
Funcții și subrutine. Aceasta include o explicație a ceea ce are fiecare subrutină sau funcție, inclusiv domeniul de aplicare al valorilor sale de intrare și ieșire.
Variabilele și constantele programului și modul în care sunt utilizate în aplicație.
Structura generală a programului. Pentru o aplicație care funcționează pe hard disk, poate fi necesar să se descrie modulele și bibliotecile individuale ale programului, iar pentru o aplicație de internet, poate fi necesar să se descrie care pagini utilizează fișierele respective.

Imagine intitulată Scriere documentație software Pasul 2

Decideți cât de mult din documentație ar trebui să fie în interiorul codului programului și cât de mult ar trebui să fie în afară. Cu cât dezvoltați mai mult documentația tehnică în cadrul codului sursă al programului, cu atât va fi mai ușor să o actualizați și să o păstrați la același nivel cu codul și va fi, de asemenea, mai ușor să documentați diferitele versiuni ale aplicației originale. Cel puțin, documentația din cadrul codului sursă ar trebui să explice scopul funcțiilor, subrutinelor, variabilelor și constantelor.

Dacă codul sursă este deosebit de lung, poate fi documentat sub forma unui fișier de ajutor, care poate fi indexat sau poate permite căutarea prin cuvinte cheie. Acest lucru este deosebit de avantajos pentru aplicațiile în care logica programului este fragmentată pe mai multe pagini și include un număr de fișiere complementare, cum este cazul anumitor aplicații de internet.

Unele limbi de programare, cum ar fi Java și .NET Framework (Visual Basic.NET, C #), au propriile reguli pentru documentarea codului. În aceste cazuri, urmați regulile referitoare la cantitatea de documentație care trebuie inclusă împreună cu codul sursă.

Imaginea intitulată Scrieți documentația software-ului Pasul 3

Alegeți instrumentul de documentare corespunzător. Într-o anumită măsură, acest lucru este determinat de limba în care este scris codul, fie C ++, C #, Visual Basic, Java sau PHP, deoarece există instrumente specifice pentru aceste și alte limbi. În alte cazuri, unealta care trebuie utilizată este determinată în funcție de tipul de documentație necesar.

Procesoarele de text din Microsoft Word sunt potrivite pentru crearea de fișiere text în documentație separat, atâta timp cât documentația este destul de scurtă și simplă. Pentru fișiere text lungi și complexe, mulți scriitori tehnici preferă instrumente de documentare, cum ar fi Adobe FrameMaker.

Puteți crea fișiere de ajutor pentru a documenta codul sursă folosind orice instrument pentru a crea fișiere de ajutor, ca RoboHelp, Ajutor și Manual, Doc-To-ajutor, MadCap bordurare sau HelpLogix.

Metoda 2
Scrieți documentația software pentru utilizatorii finali

Imaginea intitulată Scrieți documentația software-ului Pasul 4

Determinați scopurile comerciale ale documentației dvs. Deși motivul practic că software-ul este documentat este de a ajuta utilizatorii să înțeleagă modul de utilizare a aplicației, există și alte motive, cum ar fi asistarea comercializarea de software, pentru a îmbunătăți imaginea companiei, si cel mai important, reduce costurile de suport tehnic. În unele cazuri, documentația este necesară pentru a respecta anumite reglementări sau cerințe legale.

Cu toate acestea, documentația software nu ar trebui să compenseze niciodată designul slab al interfeței. Dacă un ecran de aplicații necesită pagini și pagini de documentație pentru ao explica, este mai bine să schimbați designul ecranului și să faceți ceva mai intuitiv.

Imaginea intitulată Scrieți documentația software-ului Pasul 5

Înțelegeți pentru cine scrieți documentația pentru. În majoritatea cazurilor, utilizatorii de software știu puține despre computerele din afara sarcinilor care le permit să realizeze aplicațiile pe care le folosesc. Există mai multe moduri de a determina cum să vă satisfaceți nevoile cu documentația.

Observați titlurile profesionale pe care le au potențialii dvs. utilizatori. Un administrator de sistem poate fi un expert în mai multe programe de calculator, în timp ce un angajat care introduce datele poate cunoaște doar aplicația pe care o folosește la momentul respectiv pentru a introduce datele.

Observați utilizatorii înșiși. Deși titlurile profesionale indică de obicei ceea ce fac oamenii, pot exista variații considerabile în modul în care unele titluri sunt folosite în anumite organizații. Prin intervievarea potențialilor utilizatori, puteți avea o idee dacă aveți dreptate cu privire la ceea ce credeți că indică titlul profesional.

Respectați documentația existentă. Documentația versiunilor anterioare ale software-ului, precum și specificațiile funcționale oferă unele indicații despre ce va trebui să știe cum să utilizeze programul. Cu toate acestea, rețineți că utilizatorii finali nu sunt interesați de modul în care funcționează programul, dar ce poate face programul pentru ei.

Identificați sarcinile necesare pentru a efectua lucrarea și ce sarcini trebuie îndeplinite înainte ca celelalte sarcini să poată fi îndeplinite.

Imaginea intitulată Scrieți documentația software-ului Pasul 6

Determinați formatul adecvat (sau formatele corespunzătoare) pentru documentație. Documentația software poate fi structurată într-unul din cele două formate, manualul de referință și ghidul de utilizare. Uneori, cea mai bună abordare este folosirea unei combinații a ambelor formate.

Un manual de referință este dedicat explicării caracteristicilor individuale ale unui software (buton, bar, câmp și casetă de dialog) și modul în care funcționează. Multe fișiere de ajutor sunt scrise utilizând acest format, în special fișierele de ajutor care iau în considerare contextul și afișează un subiect relevant atunci când utilizatorul face clic pe butonul Ajutor pe un anumit ecran.

Un format de ghid de utilizare explică modul în care software-ul este utilizat pentru a efectua o anumită activitate. ghiduri de utilizare, de obicei, sunt tipărite sau PDF, cu toate că unele fișiere de ajutor includ subiecte cu privire la modul de a efectua sarcini specifice (de obicei, aceste subiecte de ajutor nu iau în considerare contextul, dar poate fi legat de alte subiectele care fac). De obicei, ghidurile de utilizare vin sub formă de tutoriale, cu un rezumat al sarcinii în introducerea și instrucțiunile în pași numerotate.

Imaginea intitulată Scrieți documentația software-ului Pasul 7

Decideți ce formă (sau formulare) ar trebui să ia documentația. documentație pentru software pentru utilizatorii finali pot lua una dintre mai multe forme: manual tipărit, documente PDF, fișierele de ajutor sau de ajutor on-line. Fiecare dintre formele este proiectat pentru a arăta utilizatorului cum se utilizează fiecare funcție a programului, fie ca pas cu pas sau ghidul în cazul Tutorial fișierelor de ajutor și ajutor online, acestea pot include demonstratii video pe lângă text și imagini.

Fișierele de ajutor online trebuie să fie indexate și să permită căutări după cuvinte cheie, astfel încât utilizatorul să poată găsi rapid informațiile pe care le caută. Deși instrumentele de creare a fișierelor de ajutor pot genera automat indexurile, este de obicei mai bine să le creați manual, folosind termenii pe care utilizatorii ar putea să le caute.

Imaginea intitulată Scrieți documentația software-ului Pasul 8

Alegeți instrumentul de documentare corespunzător. Manualele de utilizare tipărite sau PDF pot fi scrise cu un procesor de text, cum ar fi Word sau un editor de text sofisticat, cum ar fi FrameMaker, în funcție de lungimea și complexitatea acestuia. Fișierele de ajutor pot fi scrise utilizând instrumentele pentru a crea fișiere de ajutor cum ar fi RoboHelp, Ajutor și Manual, Doc-To-Help, Flare sau HelpLogix.

sfaturi

Textul ar trebui să fie organizat astfel încât să poată fi citit cu ușurință, imaginile fiind plasate cât mai aproape de textul care face referire la ele. Separați documentația în secțiuni și subiecte în mod logic. Fiecare secțiune sau subiect trebuie să abordeze o singură problemă, fie că este vorba despre o singură caracteristică sau o sarcină a programului. Subiectele înrudite pot fi abordate folosind listele "vezi și ele" sau hyperlink-urile, după cum este necesar.
Unele dintre instrumentele de documentare menționate mai sus pot fi completate cu un program care vă permite să realizați capturi de ecran, cum ar fi Snagit, dacă documentația necesită câteva capturi de ecran. Ca și în cazul altor documente, capturile ar trebui incluse pentru a explica modul în care funcționează programul, nu pentru a uimi utilizatorul.
Tonul este deosebit de important, mai ales când scrieți documentația software pentru utilizatorii finali. Denumiți utilizatorul folosind a doua persoană "tu" în loc să folosești a treia persoană "utilizatorii".