Cum să scrieți documentația software: 8 pași

Documentație de software bună - fie că este vorba de un document care conține specificațiile cerințelor pentru programatori sau testere, un document tehnic pentru utilizatorii interni, manualul pentru utilizarea software-ului sau a programelor solicită utilizatorilor - ajută o persoană care lucrează cu software, să înțeleagă caracteristicile sale caracteristice și Funcții. Urmați sfaturile - Cum să scrieți documentația software pentru utilizatorii tehnici și finali.

Pași

Metoda 1 din 2:

Scrierea documentației software pentru utilizatorii tehnici.

unu. Determinați ce informații trebuie menționate. Documentele privind cerințele software servesc ca un manual de referință pentru designerii de interfață de utilizator, programatori care scriu cod și testeri care verifică dacă software-ul funcționează după cum urmează. Informațiile exacte depind de programul însuși, totuși, pot include următoarele:

Fișiere cheie în aplicație. Acestea pot fi fișiere create de echipa dezvoltatorului, bazele de date cauzate în timpul operațiunii de software și programele de servicii ale terților.
Funcții și subrutine. Este indicat aici că fiecare funcție și subrutină face, inclusiv valorile de intrare și ieșire.
Variabilele software și constantă și modul în care sunt utilizate în aplicație.
Structura generală a programului. Pentru aplicațiile bazate pe disc, probabil că veți avea nevoie de o descriere a blocurilor individuale și a bibliotecilor de programe, în timp ce aplicațiile web vor avea nevoie de o descriere a paginilor care utilizează fișiere.

Imagine intitulată Scrierea documentației software Pasul 2

2. Decideți câte documente ar trebui să fie în codul programului și cât de mult ar trebui separat. Cu cât documentația tehnică este creată în codul programului, cu atât mai ușor va actualiza acest cod ca documentație referitoare la diferite versiuni ale aplicației originale. Cel puțin, documentația din codul programului ar trebui să explice funcțiile, subrutine, constantele software și variabilele.

Dacă codul programului este destul de lung, acesta poate fi plasat ca fișier de referință în care puteți căuta după cuvinte cheie sau indicatoare. Acesta va fi un mare plus pentru aplicațiile în care logica programului este împărțită în mai multe pagini și include numere de fișiere auxiliare, ca în anumite aplicații web.

Unele limbi de programare, cum ar fi cadrul Java sau Net (Visual Basic.NET, C #), au propriile standarde pentru codul de documentare. În astfel de cazuri, urmați instrucțiunile standard - câte documente trebuie incluse în codul programului.

Imagine intitulată Scrierea documentației software Pasul 3

3. Alegeți un instrument adecvat. Într-o oarecare măsură, acest lucru este definit de limba pe care este scris codul, fie C ++, C #, Visual Basic, Java sau PHP - pentru fiecare există propriul nostru instrument. În alte cazuri, instrumentul utilizat este determinat de tipul de documentație necesară.

Editor de text "Microsoft Word" Instrumentul de verificare pentru crearea documentației de fișiere text separate, care va fi simplă și scurtă. Pentru fișierele text lungi, mulți dezvoltatori de documentație tehnică preferă să aleagă programul Adobe Framemaker.

Fișierele de vârf pentru documentația codului software pot fi scrise utilizând orice instrument, cum ar fi RoboHelp, Ajutor și Manual, Doc-to-Help, Madcap Flare sau "Helplogix".

Metoda 2 din 2:

Scrierea documentației software pentru utilizatorii finali

unu. Identificați considerațiile comerciale pentru documentația dvs. Deși motivele funcționale pentru documentația software sunt de a ajuta utilizatorii să înțeleagă cum să utilizeze aplicația, există și alte motive, cum ar fi ajutorul pentru promovarea mărfurilor pe piață, îmbunătățirea imaginii companiei și a celui mai important lucru, reducerea costurilor de suport tehnic. În anumite cazuri, documentația este obligată să respecte anumite reguli și cerințe legale.

În nici un caz, documentația programului nu ar trebui să înlocuiască designul de interfață proastă. Dacă ecranul de aplicație necesită o mulțime de documentație explicativă, este mai bine să schimbați designul la ceva mai intuitiv.

Imagine intitulată Scrierea documentației software Pasul 5

2. Înțelegeți publicul pentru care scrieți documentația. În cele mai multe cazuri, utilizatorii de software știu puțin despre computere în plus față de sarcinile de aplicare. Există mai multe modalități de a determina modul de coordonare a nevoilor lor cu documentația.

Uită-te la profesiile deținute de potențialii dvs. utilizatori. Administratorul de sistem este probabil să fie un expert în utilizarea aplicațiilor software, în timp ce operatorul de introducere a datelor este probabil să dețină aplicația pe care o utilizează în prezent pentru introducerea datelor.

Uită-te la utilizatorii înșiși. Deși posturile lor determină în general ceea ce sunt angajați, dar există diferențe semnificative în modul în care se utilizează anumite poziții în această organizație. Realizarea unui interviu cu potențialii utilizatori, vă puteți adăuga opinia - numele postului a îndeplinit îndatoririle.

Consultați documentația existentă. Documentația pentru versiunile software anterioare oferă un concept aproximativ că utilizatorul trebuie să știe despre utilizarea programului. Cu toate acestea, amintiți-vă că utilizatorii finali nu sunt interesați de modul în care funcționează programul, este important ca ei să știe ce pot face cu ea.

Determinați sarcinile necesare pentru această lucrare și ce sarcini trebuie efectuate înainte ca aceste sarcini să poată fi efectuate.

Imagine intitulată Scrie documentația software Pasul 6

3. Determinați formatul (formatele) corespunzător al documentației. Documentația software poate fi structurată într-una din cele două formate - Ghid de referință și instrucțiuni de utilizare. Uneori este mai bine să alegeți o versiune mixtă a acestor două formate.

Ghidul de referință este conceput pentru a explica instrumentele software-ului (butoane, tabele, câmpul de dialog) și modul în care funcționează acest set de instrumente. Multe fișiere prompte sunt scrise în acest format, iar contextul solicită să afișeze subiectul dorit după ce utilizatorul face clic pe butonul "Ajutor" de pe ecranul dorit.

Instrucțiunile de utilizare explică modul de utilizare a software-ului pentru a efectua o sarcină specifică. Instrucțiunea de utilizare are adesea un ghid tipărit sau un format PDF, deși unele solicitări includ subiecte despre cum să efectuați o sarcină specifică. (Aceste subiecte de referință nu sunt, de obicei, contextuale, deși pot fi hyperlink-uri) Instrucțiunea de utilizare are adesea forma unei cărți de referință cu o descriere a sarcinii și instrucțiuni pas cu pas.

Imagine intitulată Scrierea documentației software Pasul 7

4. Decideți ce format (formate) de documentație ar trebui să fie. Documentația software pentru utilizatorii finali poate fi una sau mai multe formate: Ghid de imprimare, documente în format PDF, fișiere de vârf sau ajutor online. Fiecare dintre aceste formate este creată pentru a arăta utilizatorului cum să utilizeze fiecare funcție de program - fie o scurtă prezentare sau ghid. Ca și în cazul fișierelor prompte și al ajutorului online, documentația poate avea un videoclip demonstrativ sau un text cu imagini.

Sfaturi și fișierele de ajutor online trebuie să aibă pointeri, să caute după cuvinte cheie, care vor permite utilizatorului să găsească rapid informațiile necesare. Deși instrumentele pentru fișierele prompte pot crea automat pointeri, este mai bine să faceți acest lucru utilizând manual termenii pe care utilizatorii vor deveni cel mai probabil căutarea.

Imagine intitulată Scrierea documentației software Pasul 8

cinci. Selectați un instrument adecvat pentru crearea documentației. Ghidurile de imprimare sau formatul PDF pot fi scrise în editori de text, cum ar fi "Word" sau "Framemaker", în funcție de lungimea și complexitatea manualului. Fișierele de vârf pot fi scrise folosind astfel de instrumente de dezvoltare cum ar fi "RoboHelp", "Ajutor și Manual", "Doc-to-Help", "Flare", "Helplogix" sau "HelpServer".

sfaturi

Textul ar trebui să fie ușor de citit, imaginile ar trebui să fie amplasate cât mai aproape de textul în care aparțin. Glisați documentația pentru secțiuni și teme logice. Fiecare secțiune sau subiect ar trebui să se refere la o anumită întrebare, fie că este vorba de un program sau o sarcină. Întrebările asociate trebuie indicate "pentru a viziona și" cu un hyperlink, dacă este necesar.
Toate instrumentele de creare a documentației care au fost enumerate mai sus pot fi completate de programul de capturi de ecran, cum ar fi Snagit, dacă documentația necesită un anumit număr de capturi de ecran. Ca și în cazul celeilalte documente, capturile de ecran ar trebui să explice modul în care funcționează software-ul și nu să inducă în eroare utilizatorul.
De asemenea, este importantă tonul documentației de scriere, mai ales dacă este scrisă pentru utilizatorii finali. Utilizați cea de-a doua față "dvs.", în loc de o terță parte "utilizatori".

De ce ai nevoie

Instrument pentru scrierea documentației / Debula
Instrument pentru crearea de capturi de ecran