Documentație software
Acest articol sau secțiune despre subiectul software nu menționează sursele necesare sau cei prezenți sunt insuficienți . |
Documentația software , în informatică și în special în domeniul dezvoltării de software, este un text scris care însoțește un software , cu scopul de a explica ce funcții îndeplinește software-ul, cum este structurat și implementat și cum este utilizat.
Descriere
Tipologie
Documentația software joacă, la diferite niveluri, un rol foarte important în procesul de dezvoltare software . Printre tipurile de documentație menționăm următoarele:
- Cerințe : Acestea sunt declarații de atribute, capacități, caracteristici și calitate ale sistemului.
- Arhitectură și design : Această parte oferă o prezentare generală a software-ului prin introducerea relațiilor dintre mediu și principiile de dezvoltare utilizate în proiectarea componentelor.
- Documentație tehnică : include descrierea codului utilizat pentru implementarea proiectului, a algoritmilor și a API - urilor .
- Utilizator final : conține explicațiile personalului și manualul de utilizare.
- Marketing : include indicații privind modul de promovare a produsului și analiza cererii pieței.
Documentația privind cerințele
Documentația privind cerințele este descrierea a ceea ce trebuie sau ar trebui să facă software-ul sau a specificațiilor funcționale . Cerințele sunt produse și utilizate de toți cei implicați în producția de software: utilizatori finali, clienți, manageri de produse, vânzări și marketing, arhitecți, ingineri software , designeri de interacțiuni, dezvoltatori sau testeri. Din acest motiv, documentația privind cerințele are multe scopuri diferite.
Cerințele vin într-o varietate de stiluri, notații și formalități. Cerințele pot fi orientate spre obiective (de exemplu, mediu de lucru distribuit) sau orientate spre proiectare (de exemplu, funcția de construire poate fi pornită făcând clic dreapta și selectând funcția „construiți”). Ele pot fi specificate ca instrucțiuni în limbaj non-tehnic, ca figuri desenate, ca formule matematice detaliate sau ca o combinație a tuturor.
Cerințele pot fi implicite și greu de descoperit. Nu este întotdeauna ușor să știți exact câte și ce tipuri de documentație sunt necesare și câte pot fi lăsate în componența documentației de arhitectură și proiectare, de asemenea, este dificil să știți cum să documentați cerințele, având în vedere varietatea de oameni care trebuie să citiți-l și folosiți-l. Din acest motiv, documentația cerințelor este adesea incompletă sau inexistentă și fără documentația adecvată, modificările software-ului devin mai predispuse la erori. Necesitatea documentației variază în funcție de scopul proiectului : în cazul proiectelor mici pentru a dezvolta aplicații de scurtă durată (de exemplu pentru o campanie), cantitatea de documentație este mult mai mică decât pentru proiectele care privesc probleme de securitate (de exemplu în cazul la proiectarea software-ului unui sistem de energie nucleară ).
Documentație de arhitectură și proiectare
Documentația de arhitectură este un tip special de document de proiectare . În documentația arhitecturală există puține specificații, dar direct legate de cod : acest lucru nu descrie modul în care un anumit modul trebuie să fie programat, ci trebuie să explice de ce există modulul, acesta este practic modul în care este structurat software-ul.
O parte foarte importantă a documentației de proiectare în dezvoltarea unui proiect software este Documentul de proiectare a bazei de date (DDD). Acesta conține elemente conceptuale, logice și fizice ale proiectării și include, de asemenea, informații formale pe care oamenii le interacționează cu baza de date . Scopul creării documentului este pregătirea unei resurse comune care poate fi utilizată de toți actorii care participă la proiect.
Utilizatorii potențiali sunt:
- Proiectant de baze de date;
- Dezvoltator de baze de date;
- Administratorul bazei de date;
- Designer de aplicații;
- Dezvoltator de aplicatii.
Vorbind despre baza de date relațională, documentul ar trebui să conțină următoarele părți:
- Schema entitate-relație ;
- Definirea entităților și atributelor;
- Relațiile și atributele acestora;
- Chei de candidat;
- Atribute și Tuples;
- Schema relațională;
- Tabelele, atributele și proprietățile;
- Vizualizări;
- Chei primare și chei străine;
- Cardinalitatea.
Documentatie tehnica
Documentația tehnică este tot ceea ce înseamnă majoritatea programatorilor atunci când utilizează termenul de documentație software. Când creați software, codul sursă singur este insuficient. Trebuie să existe un text atașat pentru a descrie diferitele aspecte ale funcționării sale. Este important să păstrați documentația tehnică detaliată, dar nu prea detaliată pentru a o putea actualiza cu ușurință. Această documentație poate fi utilizată de dezvoltatori, testeri și chiar de clienții finali sau de clienții care utilizează software-ul.
Adesea, instrumente precum Doxygen , NDoc, javadoc , EiffelStudio, Sandcastle, ROBODoc, POD, TwinText sau Report Universal pot fi utilizate pentru a genera automat documentația codului. Acest lucru se realizează prin extragerea comentariilor găsite în codul sursă și apoi crearea documentelor de referință în format fișier text . Ideea de documentare auto-generatoare este atrăgătoare pentru programatori din diverse motive. De exemplu, deoarece este extras din codul sursă prin comentariile pe care programatorul le scrie cu referire la cod. Acest lucru face mult mai ușor să păstrați documentația actualizată.
Documentația utilizatorului
Documentația utilizatorului descrie pur și simplu modul în care software-ul poate fi utilizat. De obicei, documentația utilizatorului descrie în detaliu toate caracteristicile software-ului și îl ajută pe utilizator să utilizeze aceste funcții.
O documentație bună trebuie să meargă atât de departe încât să ofere utilizatorului asistență până la rezolvarea completă a problemelor într-un mod consecvent și simplu. Este foarte important ca documentele să nu fie confuze și, prin urmare, să fie actualizate constant. Nu este necesar să îl organizați într-o anumită ordine, dar este întotdeauna recomandabil să creați un index, astfel încât să puteți accesa cu ușurință ceea ce căutați. Există trei moduri principale în care documentația poate fi organizată:
- Tutorial : o abordare tutorială este considerată una dintre cele mai utile pentru utilizatorii noi, deoarece oferă un ghid detaliat care urmărește pas cu pas utilizatorul până la finalizarea funcționalității.
- Tematică : o abordare tematică cu capitole și secțiuni axate pe același domeniu de interes poate fi de interes mai mare pentru un utilizator intermediar.
- Referință : Comenzile sau sarcinile sunt listate pur și simplu alfabetic sau grupate logic, adesea prin indexuri și referințe încrucișate. Această din urmă abordare este cea mai utilă pentru utilizatorii avansați care știu exact ce fel de informații caută.
O problemă obișnuită în rândul utilizatorilor este că, de obicei, numai una dintre abordările enumerate este utilizată pentru a produce documentație. Este o practică obișnuită să se limiteze documentația software oferind doar informații de referință despre comenzi sau elemente din meniu.
Documentație de marketing
Pentru multe aplicații, este necesar, de asemenea, să aveți material promoțional care să încurajeze utilizatorul obișnuit să caute informații despre produs. Acest tip de documentare are trei scopuri principale:
- Creați interes pentru potențialul utilizator și insuflați-i dorința de a fi implicat.
- Informați exact despre funcționalitatea produsului, astfel încât așteptările utilizatorului să fie aliniate cu ceea ce oferă produsul
- Explicați poziția produsului față de alternativele care există pe piață.
