Cum se scrie documentația software

Documentația software bună - fie pentru programatori și testere, pentru documente tehnice ale utilizatorilor interni, fie pentru manuale software și fișiere de ajutor pentru utilizatorii finali - ajută persoana care lucrează cu software-ul să-și înțeleagă funcțiile și caracteristicile. Documentația bună este specifică, concisă și relevantă, oferind toate informațiile importante persoanelor care utilizează programul. Continuați să citiți instrucțiunile privind modul de scriere a documentației software pentru utilizatorii finali și tehnici.

conținut

Pași
Metoda 1scrierea documentației software pentru utilizatorii tehnici
Metoda 2scrierea documentației software către utilizatorii finali
Sfaturi
Materiale necesare
Surse și cotatii

pași

Metoda 1
Scrierea documentației software pentru utilizatorii tehnici

Imagine intitulată Scriere documentație software Pasul 1

Determinați ce informații să includeți. Documentele cu specificație software servesc drept manuale de referință pentru designerii UI, programatori de scriere de coduri și testeri care verifică dacă software-ul funcționează conform destinației. Informațiile exacte depind de programul în cauză, dar pot include:

Fișiere cheie din cadrul aplicației. Acestea pot include fișiere create de echipa de dezvoltare, baze de date accesate în timpul funcționării programului și utilități terță parte.
Funcții și subrutine. Include aici o explicație a ceea ce face fiecare funcție sau subrutină, inclusiv gama ei de valori 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 pe disc, aceasta poate însemna descrierea modulelor și a bibliotecilor individuale ale programului, în timp ce pentru o aplicație web, o descriere a paginilor care utilizează fișierele.

Imagine intitulată Scriere documentație software Pasul 2

Decideți cât de mult documentație ar trebui să fie în interiorul codului programului și cât de mult ar trebui să fie separate de el. Cu cât documentația tehnică este mai dezvoltată în cadrul sursei programului, cu atât va fi mai ușor să mențină și să mențină codul, precum și să documenteze 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 căutat cu cuvinte cheie. Acesta este un avantaj deosebit pentru aplicațiile în care logica programului este fragmentată pe mai multe pagini și include mai multe fișiere suplimentare, precum și anumite aplicații web.
Unele limbi de programare, cum ar fi Java și .NET Framework (Visual Basic .NET, C #), au programe proprii pentru documentarea codului. În astfel de cazuri, urmați standardele pentru cantitatea de documentație care trebuie inclusă.

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

Alegeți instrumentul de documentare potrivit. Într-o anumită măsură, acest lucru va fi determinat de limba în care este scris codul, fie în 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ă de tipul de documentație necesar.

Programele de procesare a cuvintelor pentru Microsoft Word sunt potrivite pentru crearea de fișiere text separate atât timp cât documentația este relativ scurtă și simplă. Pentru fișiere text lungi și complexe, mulți scriitori tehnici preferă un instrument de documentare, cum ar fi Adobe FrameMaker.
Fișierele de asistență pentru documentarea codului sursă pot fi produse cu orice instrument de scriere a ajutorului, cum ar fi RoboHelp, Ajutor și Manual, Doc-To-Help, MadCap Flare sau HelpLogix.

Metoda 2
Scrierea documentației software către utilizatorii finali

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

Determinați scopurile de afaceri ale documentației. Deși motivul pentru aceasta este de a ajuta utilizatorii să înțeleagă modul de utilizare a aplicației, există și alte motive, cum ar fi ajutorul pentru promovarea programului, îmbunătățirea imaginii companiei și, cel mai important, reducerea costurilor suportului tehnic. În unele cazuri, documentația trebuie să respecte anumite reglementări sau alte cerințe legale.

În nici un caz, însă, documentația nu ar trebui să înlocuiască un design de interfață prost. Dacă un ecran de aplicație necesită pagini și pagini de documentație pentru ao explica, este mai bine să schimbați designul pentru al face mai intuitiv.

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

Înțelegeți publicul pentru care scrieți documentația. În cele mai multe cazuri, utilizatorii de software au puține cunoștințe despre computere dincolo de sarcinile aplicațiilor pe care le utilizează. Există mai multe modalități de a determina cum să vă satisfaceți nevoile cu documentația dvs.

Rețineți numele de locuri de muncă ale potențialilor utilizatori. Este posibil ca un administrator de sistem să fie competent în mai multe aplicații software, în timp ce un funcționar de introducere a datelor va cunoaște probabil numai aplicația pe care o folosește pentru a introduce date.
Observați utilizatorii înșiși. Deși titlurile angajaților indică adesea ce fac oamenii, pot exista variații considerabile în modul în care anumite titluri sunt utilizate într-o anumită organizație. Prin intervievarea potențialilor utilizatori, puteți afla dacă impresiile dvs. privind nevoile dvs. sunt corecte sau nu.
Uită-te la documentația existentă. Documentația cu privire la versiunile anterioare ale software-ului, precum și specificațiile funcționale oferă unele indicații despre ce va trebui să știe utilizatorul pentru a utiliza programul. Rețineți totuși că utilizatorii finali nu sunt interesați de modul în care funcționează programul, ci mai degrabă de ceea ce poate face pentru ei.
Identificați sarcinile necesare pentru a face treaba și ce sarcini trebuie îndeplinite înainte de a lucra.

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

Determinați formatele adecvate pentru documentație. Documentația software poate fi structurată în 1 sau 2 formate, manualul de referință și ghidul utilizatorului. Uneori o combinație de formate este cea mai bună abordare.

Un format manual de referință este dedicat explicării caracteristicilor individuale ale unei aplicații (butoane, file, câmpuri și casete de dialog) și a modului în care acestea funcționează. Multe fișiere de ajutor sunt scrise în acest format, care afișează un subiect relevant ori de câte ori un utilizator face clic pe butonul de ajutor de pe un anumit ecran.
Un format de ghid de utilizare explică modul de utilizare a programului pentru a efectua o anumită activitate. Aceste ghiduri sunt, de obicei, tipărite sau afișate în fișiere PDF, deși unele fișiere de ajutor includ subiecte referitoare la modul de efectuare a anumitor sarcini (aceste subiecte de ajutor sunt, în general, sensibile la context, deși pot conține linkuri către subiecte care sunt). Ghidurile de utilizatori se bazează, în general, sub forma unor tutoriale, cu un rezumat al sarcinilor care trebuie efectuate în introducere și instrucțiunile date în etapele numerotate.

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

Decideți ce documente ar trebui să ia documentația. Documentația software pentru utilizatorii finali poate lua una dintre următoarele forme: manuale tipărite, documente PDF, fișiere de ajutor sau ajutor online. Fiecare formular este făcut pentru a arăta utilizatorului cum să folosească fiecare dintre funcțiile programului, fie sub formă de walkthrough sau tutorial - în cazul fișierelor de ajutor și ajutor online, se pot include videoclipuri demo, precum și text și imagini.

Fișierele de ajutor ar trebui să fie indexate și căutate după cuvinte cheie, astfel încât utilizatorii să găsească rapid informațiile pe care le doresc. Deși instrumentele de scris pot genera indexuri în mod automat, cel mai bine este să le faceți manual, folosind termenii pe care utilizatorii pot căuta.

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

Alegeți instrumentul de documentare potrivit. Manualele tipărite sau PDF pot fi scrise cu un program de procesare a textelor, cum ar fi Word sau un editor de text sofisticat, cum ar fi FrameMaker, în funcție de mărimea și complexitatea acestora. Fișierele de ajutor pot fi scrise cu ajutorul unui instrument specific pentru fișierele de ajutor, cum ar fi RoboHelp, Ajutor și Manual, Doc-To-Help, Flare, HelpLogix sau HelpServer.

sfaturi

Textul trebuie să fie organizat pentru o citire ușoară, imaginile fiind poziționate aproape de textul care le este asociat. Împărțiți documentația în secțiuni și subiecte într-un mod logic. Fiecare secțiune sau subiect poate fi referit cu un "vezi de asemenea" sau link-uri, după cum este necesar.
Instrumentele de documentare enumerate mai sus pot fi completate cu un program de screenshot-uri, cum ar fi Snagit, dacă documentația necesită mai multe capturi de ecran. Ca și în cazul altor documente, aceste imagini trebuie să fie incluse pentru a explica modul în care funcționează programul, nu pentru a impresiona utilizatorul.
Tonul este deosebit de important, mai ales atunci când se scrie documentația pentru utilizatorii finali. Sunați-le "voi" în loc de "utilizatori".