O documentație software bună, fie că este vorba despre specificații pentru programatori și testeri, documente tehnice pentru utilizatorii interni sau manuale și fișiere de ajutor pentru utilizatorii finali, îi va ajuta pe utilizatori să înțeleagă caracteristicile și funcțiile software-ului. O documentație bună este documentația specifică, clară și relevantă, cu toate informațiile de care are nevoie utilizatorul. Acest articol vă va ghida să scrieți documentația software pentru utilizatorii tehnici și utilizatorii finali.
Etapa
Metoda 1 din 2: Scrierea documentației software pentru utilizatorii tehnici
Pasul 1. Aflați ce informații să includeți
Documentul de specificații este utilizat ca manual de referință pentru proiectanții de interfețe, programatorii care scriu cod și testerii care verifică performanța software-ului. Informațiile care trebuie incluse vor depinde de programul creat, dar pot include următoarele:
- Fișierele importante din aplicație, cum ar fi fișierele create de echipa de dezvoltare, bazele de date accesate în timp ce programul rulează și aplicațiile de la terți.
- Funcții și subrutine, inclusiv o explicație a utilizării funcției / subrutinei, valorilor de intrare și ieșire.
- Variabilele și constantele programului și modul în care sunt utilizate.
- Structura generală a programului. Pentru programele bazate pe unități, poate fi necesar să descrieți fiecare modul și bibliotecă. Sau, dacă scrieți un manual pentru un program web, poate fi necesar să explicați fișierele pe care le folosește fiecare pagină.
Pasul 2. Decideți ce nivel de documentație ar trebui să fie prezent și separabil de codul programului
Cu cât este inclusă mai multe documente tehnice în codul programului, cu atât va fi mai ușor să îl actualizați și să îl întrețineți, precum și să explicați diferitele versiuni ale programului. Cel puțin, documentația din codul programului ar trebui să includă utilizarea funcțiilor, subrutinelor, variabilelor și constantelor.
- Dacă codul dvs. sursă este lung, puteți scrie documentație într-un fișier de ajutor, care poate fi apoi indexat sau căutat cu anumite cuvinte cheie. Fișierele de documentare separate sunt utile dacă logica programului este împărțită pe mai multe pagini și include fișiere de asistență, cum ar fi o aplicație web.
- Unele limbaje de programare (cum ar fi Java, Visual Basic. NET sau C #) au propriile standarde de documentare a codului. În astfel de cazuri, urmați documentația standard care trebuie inclusă în codul sursă.
Pasul 3. Selectați instrumentul de documentare adecvat
În unele cazuri, instrumentul de documentare este determinat de limbajul de programare utilizat. Limbajele C ++, C #, Visual Basic, Java, PHP și altele au propriile lor instrumente de documentare. Cu toate acestea, dacă nu, instrumentele utilizate vor depinde de documentația necesară.
- Un procesor de text, cum ar fi Microsoft Word, este potrivit pentru crearea fișierelor text ale documentelor, atât timp cât documentația este concisă și simplă. Pentru a crea documentație lungă cu text complex, majoritatea scriitorilor tehnici aleg un instrument de documentare specializat, cum ar fi Adobe FrameMaker.
- Fișierele de ajutor pentru documentarea codului sursă pot fi create cu un program generator de fișiere de asistență, cum ar fi RoboHelp, Help and Manual, Doc-To-Help, MadCap Flare sau HelpLogix.
Metoda 2 din 2: Scrierea documentației software pentru utilizatorii finali
Pasul 1. Cunoașteți motivele de afaceri care stau la baza creării manualului
În timp ce principalul motiv al documentației software este de a ajuta utilizatorii să înțeleagă modul de utilizare a aplicației, există și alte câteva motive care pot sta la baza creării documentației, cum ar fi ajutarea departamentului de marketing să vândă aplicația, îmbunătățirea imaginii companiei și reducerea suportului tehnic cheltuieli. În unele cazuri, documentația este necesară pentru a respecta reglementările sau alte cerințe legale.
Cu toate acestea, documentația nu este un bun substitut pentru o interfață. Dacă o aplicație necesită multă documentație pentru a funcționa, ar trebui să fie concepută pentru a fi mai intuitivă
Pasul 2. Cunoașteți publicul țintă al documentației
În general, utilizatorii de software au cunoștințe de calculator limitate dincolo de aplicațiile utilizate de aceștia. Există mai multe modalități de a-și satisface nevoile de documentare:
- Acordați atenție titlului utilizatorului de software. De exemplu, administratorul de sistem înțelege în general diverse aplicații informatice, în timp ce secretarul știe doar aplicațiile pe care le folosește pentru a introduce date.
- Acordați atenție utilizatorilor de software. Deși pozițiile lor sunt în general compatibile cu sarcinile îndeplinite, aceste poziții pot avea sarcini de muncă diferite, în funcție de locul de desfășurare a activității. Prin intervievarea potențialilor utilizatori, puteți afla dacă evaluarea dvs. a titlului postului este corectă.
- Acordați atenție documentației existente. Documentația și specificațiile funcționalității software pot arăta ce trebuie să știe utilizatorii pentru a le utiliza. Cu toate acestea, rețineți că este posibil ca utilizatorii să nu fie interesați să cunoască „interiorul” programului.
- Aflați ce este nevoie pentru a finaliza o sarcină și ce este nevoie înainte de a o putea finaliza.
Pasul 3. Determinați formatul adecvat pentru documentație
Documentația software poate fi aranjată în 1 sau 2 formate, și anume cărți de referință și manuale. Uneori, combinarea celor două formate este o soluție bună.
- Formatele de referință sunt utilizate pentru a descrie toate funcțiile software, cum ar fi butoanele, filele, câmpurile și casetele de dialog și modul în care funcționează. Unele fișiere de ajutor sunt scrise în acest format, în special cele care sunt sensibile la context. Când utilizatorul face clic pe Ajutor într-un anumit ecran, utilizatorul va primi subiectul relevant.
- Formatul manual este folosit pentru a explica cum se face ceva cu software-ul. Manualele sunt, în general, în format tipărit sau PDF, deși unele pagini de ajutor includ, de asemenea, instrucțiuni despre cum să faceți anumite lucruri. (În general, formatele manuale nu sunt sensibile la context, dar pot fi legate de subiecte contextuale). Manualele sunt, în general, sub forma unui ghid, cu un rezumat al sarcinilor care trebuie îndeplinite într-o descriere și un ghid formatat în etape.
Pasul 4. Decideți tipul de documentație
Documentația software pentru utilizatori poate fi ambalată într-unul sau mai multe dintre următoarele formate: manuale tipărite, fișiere PDF, fișiere de ajutor sau ajutor online. Fiecare tip de documentație este conceput pentru a vă arăta cum să utilizați funcțiile software-ului, indiferent dacă este un ghid sau un tutorial. Documentația online și paginile de ajutor pot include, de asemenea, videoclipuri demonstrative, text și imagini statice.
Fișierele de asistență și asistență online ar trebui indexate și căutate folosind cuvinte cheie, astfel încât utilizatorii să poată găsi rapid informațiile de care au nevoie. Deși o aplicație generatoare de fișiere de ajutor poate crea automat un index, este totuși recomandat să creați manual un index folosind cuvinte cheie căutate frecvent
Pasul 5. Selectați instrumentul de documentare adecvat
Manuale tipărite sau PDF-uri pot fi create cu un program de procesare a textului, cum ar fi Word sau un editor de text avansat, cum ar fi FrameMaker, în funcție de lungimea și complexitatea fișierului. Fișierele de ajutor pot fi scrise cu un program de creare a fișierelor de ajutor, cum ar fi RoboHelp, Help and Manual, Doc-To-Help, Flare, HelpLogix sau HelpServer.
sfaturi
- Textul documentației programului ar trebui să fie structurat astfel încât să fie ușor de citit. Plasați imaginea cât mai aproape de textul adecvat. Defalcați în mod logic documentația pe secțiuni și subiecte. Fiecare secțiune sau subiect ar trebui să descrie o problemă specifică, atât sarcinile, cât și caracteristicile programului. Problemele conexe pot fi explicate cu linkuri sau liste de referințe.
- Fiecare dintre instrumentele de documentare descrise în acest articol poate fi completat de un program de realizare a capturilor de ecran, cum ar fi SnagIt dacă documentația dvs. necesită capturi de ecran multiple. La fel ca orice altă documentație, ar trebui să includeți, de asemenea, capturi de ecran pentru a explica modul în care funcționează aplicația, în loc să „ademenească” utilizatorul.
- Acordarea atenției stilului este foarte importantă, mai ales dacă scrieți documentație software pentru utilizatorii finali. Adresați-vă utilizatorilor cu pronumele „dvs.”, în loc de „utilizator”.
