Pozdrav, Habr! Moje ime je Lesha, ja sam sistemski analitičar za jedan od Alfa-Bank timova proizvoda. Sada razvijam novu online banku za pravne osobe i samostalne poduzetnike.
A kad si analitičar, pogotovo u takvom kanalu, ne možeš nikuda bez dokumentacije i bliskog rada s njom. A dokumentacija je nešto što uvijek izaziva puno pitanja. Zašto web aplikacija nije opisana? Zašto u specifikaciji stoji kako bi usluga trebala funkcionirati, a uopće ne funkcionira tako? Zašto samo dvije osobe, od kojih je jedna napisala, mogu razumjeti specifikaciju?
Međutim, dokumentacija se ne može zanemariti iz očitih razloga. A kako bismo si olakšali život, odlučili smo procijeniti kvalitetu dokumentacije. Kako smo to točno napravili i do kojih smo zaključaka došli nalazi se u nastavku.
Kvaliteta dokumentacije
Kako se u tekstu nekoliko desetaka puta ne bi ponavljalo “Nova Internet banka”, napisat ću NIB. Sada imamo više od desetak timova koji rade na razvoju NIB-a za poduzetnike i pravne osobe. Štoviše, svaki od njih ili izrađuje vlastitu dokumentaciju za novu uslugu ili web aplikaciju od nule, ili mijenja trenutnu. Može li ovakvim pristupom dokumentacija u načelu biti kvalitetna?
A kako bismo odredili kvalitetu dokumentacije, identificirali smo tri glavne karakteristike.
- Mora biti kompletan. Ovo zvuči prilično kapetanski, ali važno je napomenuti. Treba detaljno opisati sve elemente implementiranog rješenja.
- Mora biti relevantan. Odnosno, odgovara trenutnoj implementaciji samog rješenja.
- Trebalo bi biti razumljivo. Tako da osoba koja ga koristi razumije točno kako se rješenje implementira.
Ukratko – potpuna, ažurna i razumljiva dokumentacija.
Intervju
Kako bismo ocijenili kvalitetu dokumentacije, odlučili smo intervjuirati one koji s njom izravno rade: analitičare NIB-a. Ispitanici su zamoljeni da ocijene 10 tvrdnji prema shemi “Na ljestvici od 1 do 5 (uopće se ne slažem – u potpunosti se slažem).”
Izjave su odražavale karakteristike kvalitativne dokumentacije i mišljenje sastavljača ankete o dokumentima NIB-a.
- Dokumentacija za NIB aplikacije je ažurna i potpuno usklađena s njihovom implementacijom.
- Implementacija NIB aplikacija je u potpunosti dokumentirana.
- Dokumentacija za NIB aplikacije potrebna je samo za funkcionalnu podršku.
- Dokumentacija za NIB aplikacije aktualna je u trenutku njihove predaje za funkcionalnu podršku.
- Programeri NIB aplikacija koriste se dokumentacijom kako bi razumjeli što trebaju implementirati.
- Postoji dovoljno dokumentacije za NIB aplikacije da biste razumjeli kako su implementirane.
- Odmah ažuriram dokumentaciju o NIB projektima ako su finalizirani (od strane mog tima).
- Programeri NIB aplikacija pregledavaju dokumentaciju.
- Jasno mi je kako pripremiti dokumentaciju za NIB projekte.
- Razumijem kada napisati/ažurirati dokumentaciju za NIB projekte.
Jasno je da jednostavno odgovaranje na "Od 1 do 5" možda neće otkriti potrebne detalje, tako da osoba može ostaviti komentar na svaku stavku.
Sve smo to napravili preko korporativnog Slacka – jednostavno smo poslali poziv sistemskim analitičarima da popune anketu. Bilo je 15 analitičara (9 iz Moskve i 6 iz St. Petersburga). Nakon završene ankete, za svaku od 10 tvrdnji generirali smo prosječnu ocjenu koju smo potom standardizirali.
Evo što se dogodilo.
Istraživanje je pokazalo da iako su analitičari skloni vjerovati da je implementacija NIB aplikacija u potpunosti dokumentirana, ne daju jednoznačnu suglasnost (0.2). Kao konkretan primjer istaknuli su da niz baza podataka i redova čekanja iz postojećih rješenja nije dokumentirano obuhvaćeno. Programer može reći analitičaru da nije sve dokumentirano. No teza da programeri pregledavaju dokumentaciju također nije dobila jednoznačnu podršku (0.33). Odnosno, rizik nepotpunog opisa implementiranih rješenja ostaje.
Relevantnost je lakša – iako opet nema jasnog dogovora (0,13), analitičari su i dalje skloni dokumentaciju smatrati relevantnom. Komentari su nam omogućili da shvatimo da su problemi s relevantnošću češće na početku nego u sredini. Međutim, o podršci nam nisu ništa napisali.
Što se tiče toga shvaćaju li sami analitičari kada je potrebno napisati i ažurirati dokumentaciju, sporazum je bio puno ujednačeniji (1,33), uključujući i njegov dizajn (1.07). Ono što je ovdje uočeno kao neugodnost je nepostojanje jedinstvenih pravila za vođenje dokumentacije. Stoga, kako ne bi uključili modus “Tko u šumu, tko po drva”, moraju raditi na temelju primjera postojeće dokumentacije. Stoga je korisna želja stvoriti standard za upravljanje dokumentima i razviti predloške za njihove dijelove.
Dokumentacija za NIB aplikacije aktualna je u trenutku podnošenja za funkcionalnu podršku (0.73). To je i razumljivo, jer je jedan od kriterija za prijavu projekta za funkcionalnu potporu ažurna dokumentacija. Također je dovoljno razumjeti implementaciju (0.67), iako ponekad ostaju pitanja.
No ono s čime se ispitanici nisu složili (prilično jednoglasno) jest da je dokumentacija za NIB aplikacije u načelu potrebna samo za funkcionalnu podršku (-1.53). Kao potrošači dokumentacije najčešće su spominjani analitičari. Ostatak tima (developeri) - puno rjeđe. Štoviše, analitičari vjeruju da programeri ne koriste dokumentaciju da bi razumjeli što trebaju implementirati, iako ne jednoglasno (-0.06). To se, inače, očekuje iu uvjetima u kojima razvoj koda i pisanje dokumentacije teku paralelno.
Što je krajnji zaključak i zašto su nam potrebni ovi brojevi?
Kako bismo poboljšali kvalitetu dokumenata, odlučili smo učiniti sljedeće:
- Zamolite programera da pregleda pisane dokumente.
- Ako je moguće, ažurirajte dokumentaciju na vrijeme, s prednje strane.
- Izradite i usvojite standard za dokumentiranje NIB projekata tako da svatko može brzo razumjeti koje elemente sustava i kako točno treba opisati. Pa, razvijte odgovarajuće predloške.
Sve bi to trebalo pomoći podići kvalitetu dokumenata na novu razinu.
Barem se nadam.
Izvor: www.habr.com