Bună, Habr! Numele meu este Lesha, sunt analist de sisteme pentru una dintre echipele de produse ale Alfa-Bank. Acum dezvolt o nouă bancă online pentru persoane juridice și antreprenori individuali.
Și când ești analist, mai ales într-un astfel de canal, nu poți ajunge nicăieri fără documentare și să lucrezi îndeaproape cu ea. Iar documentarea este ceva care ridică întotdeauna multe întrebări. De ce nu este descrisă aplicația web? De ce specificația indică cum ar trebui să funcționeze serviciul, dar nu funcționează deloc așa? De ce doar două persoane, dintre care una a scris-o, pot înțelege specificația?
Cu toate acestea, documentația nu poate fi ignorată din motive evidente. Și pentru a ne ușura viața, am decis să evaluăm calitatea documentației. Cum exact am făcut acest lucru și la ce concluzii am ajuns se află mai jos.
Calitatea documentatiei
Pentru a nu repeta „New Internet Bank” de câteva zeci de ori în text, voi scrie NIB. Acum avem peste o duzină de echipe care lucrează la dezvoltarea NIB pentru antreprenori și persoane juridice. Mai mult, fiecare dintre ele fie își creează propria documentație pentru un nou serviciu sau aplicație web de la zero, fie face modificări la cea actuală. Cu această abordare, documentația poate fi în principiu de înaltă calitate?
Și pentru a determina calitatea documentației, am identificat trei caracteristici principale.
- Trebuie să fie complet. Sună mai degrabă a căpitanului, dar este important de reținut. Ar trebui să descrie în detaliu toate elementele soluției implementate.
- Trebuie să fie actual. Adică, corespund implementării curente a soluției în sine.
- Ar trebui să fie de înțeles. Pentru ca persoana care o folosește să înțeleagă exact cum este implementată soluția.
Pentru a rezuma - documentație completă, actualizată și ușor de înțeles.
Опрос
Pentru a evalua calitatea documentației, am decis să intervievăm cei care lucrează direct cu ea: analiștii NIB. Respondenții au fost rugați să evalueze 10 afirmații conform schemei „Pe o scară de la 1 la 5 (complet dezacord - complet de acord).”
Declarațiile au reflectat caracteristicile documentației calitative și opinia celor care au compilat sondajul cu privire la documentele BNI.
- Documentația pentru aplicațiile NIB este actualizată și pe deplin consecventă cu implementarea acestora.
- Implementarea aplicațiilor NIB este complet documentată.
- Documentația pentru aplicațiile NIB este necesară doar pentru suport funcțional.
- Documentația pentru aplicațiile NIB este actuală la momentul depunerii acestora pentru suport funcțional.
- Dezvoltatorii de aplicații NIB folosesc documentația pentru a înțelege ce trebuie să implementeze.
- Există suficientă documentație pentru ca aplicațiile NIB să înțeleagă cum sunt implementate.
- Actualizez prompt documentația privind proiectele NIB dacă acestea sunt finalizate (de echipa mea).
- Dezvoltatorii de aplicații NIB examinează documentația.
- Am o înțelegere clară a modului de pregătire a documentației pentru proiectele NIB.
- Înțeleg când să scriu/actualizez documentația pentru proiectele NIB.
Este clar că simplul răspuns „De la 1 la 5” ar putea să nu dezvăluie detaliile necesare, așa că o persoană ar putea lăsa un comentariu la fiecare articol.
Am făcut toate acestea prin intermediul companiei Slack - pur și simplu le-am trimis o invitație analiștilor de sistem pentru a participa la un sondaj. Au fost 15 analiști (9 din Moscova și 6 din Sankt Petersburg). După finalizarea sondajului, am generat un scor mediu pentru fiecare dintre cele 10 afirmații, pe care apoi l-am standardizat.
Iată ce sa întâmplat.
Sondajul a arătat că, deși analiștii sunt înclinați să creadă că implementarea aplicațiilor NIB este pe deplin documentată, ei nu oferă un acord clar (0.2). Ca exemplu specific, ei au subliniat că o serie de baze de date și cozi din soluțiile existente nu au fost acoperite de documentație. Dezvoltatorul este capabil să-i spună analistului că nu totul este documentat. Dar teza conform căreia dezvoltatorii revizuiesc documentația nu a primit, de asemenea, suport fără echivoc (0.33). Adică, riscul unei descrieri incomplete a soluțiilor implementate rămâne.
Relevanța este mai ușoară - deși din nou nu există un acord clar (0,13), analiștii sunt încă înclinați să considere documentația relevantă. Comentariile ne-au permis să înțelegem că problemele cu relevanță sunt mai des în față decât la mijloc. Cu toate acestea, nu ne-au scris nimic despre susținere.
În ceea ce privește dacă analiștii înșiși înțeleg când este necesar să scrie și să actualizeze documentația, acordul a fost mult mai uniform (1,33), inclusiv proiectarea acestuia (1.07). Ceea ce s-a notat aici ca un inconvenient a fost lipsa unor reguli uniforme de păstrare a documentației. Prin urmare, pentru a nu activa modul „Cine merge în pădure, cine primește lemne de foc”, trebuie să lucreze pe baza exemplelor de documentație existentă. Prin urmare, o dorință utilă este de a crea un standard pentru gestionarea documentelor și de a dezvolta șabloane pentru părțile lor.
Documentația pentru aplicațiile NIB este actuală la momentul depunerii pentru suport funcțional (0.73). Acest lucru este de înțeles, deoarece unul dintre criteriile de depunere a unui proiect pentru suport funcțional este documentația la zi. De asemenea, este suficient să înțelegem implementarea (0.67), deși uneori rămân întrebări.
Dar cu ceea ce respondenții nu au fost de acord (destul de unanimitate) a fost că documentația pentru aplicațiile NIB, în principiu, este necesară doar pentru suport funcțional (-1.53). Analiștii au fost menționați cel mai des ca consumatori de documentație. Restul echipei (dezvoltatori) - mult mai rar. Mai mult, analiștii consideră că dezvoltatorii nu folosesc documentația pentru a înțelege ce trebuie să implementeze, deși nu în unanimitate (-0.06). Acest lucru, apropo, este de așteptat și în condițiile în care dezvoltarea codului și scrierea documentației se desfășoară în paralel.
Care este concluzia și de ce avem nevoie de aceste numere?
Pentru a îmbunătăți calitatea documentelor, am decis să facem următoarele:
- Cereți dezvoltatorului să examineze documentele scrise.
- Dacă este posibil, actualizați documentația în timp util, în primul rând.
- Creați și adoptați un standard pentru documentarea proiectelor NIB, astfel încât toată lumea să poată înțelege rapid ce elemente de sistem și cum trebuie descrise exact. Ei bine, dezvoltați șabloane adecvate.
Toate acestea ar trebui să contribuie la ridicarea calității documentelor la un nou nivel.
Cel puțin așa sper.
Sursa: www.habr.com