Zdravo, Habr! Moje ime je Lesha, ja sam sistemski analitičar za jedan od proizvodnih timova Alfa-Bank. Sada razvijam novu internet banku za pravna lica i fizička lica.
A kada ste analitičar, pogotovo u takvom kanalu, ne možete nigdje bez dokumentacije i bliskog rada s njom. A dokumentacija je nešto što uvijek otvara mnoga pitanja. Zašto web aplikacija nije opisana? Zašto specifikacija pokazuje kako bi usluga trebala funkcionirati, a ona uopće ne funkcionira tako? Zašto samo dvije osobe, od kojih je jedna to napisala, mogu razumjeti specifikaciju?
Međutim, dokumentacija se ne može zanemariti iz očiglednih razloga. A kako bismo sebi olakšali život, odlučili smo procijeniti kvalitet dokumentacije. Kako smo to tačno uradili i do kakvih zaključaka smo došli je u nastavku.
Kvaliteta dokumentacije
Da se u tekstu više desetina puta ne ponavlja „Nova Internet banka“, napisaću NIB. Sada imamo više od deset timova koji rade na razvoju NIB-a za preduzetnike i pravna lica. Štaviše, svaki od njih ili kreira vlastitu dokumentaciju za novu uslugu ili web aplikaciju od nule, ili mijenja trenutnu. Može li ovakvim pristupom dokumentacija u principu biti kvalitetna?
A da bismo utvrdili kvalitet dokumentacije, identifikovali smo tri glavne karakteristike.
- Mora biti kompletan. Ovo zvuči prilično kapetanski, ali važno je napomenuti. Trebalo bi detaljno opisati sve elemente implementiranog rješenja.
- Mora biti relevantno. Odnosno, odgovaraju trenutnoj implementaciji samog rješenja.
- Trebalo bi biti razumljivo. Tako da osoba koja ga koristi razumije tačno kako se rješenje implementira.
Da rezimiramo - kompletna, ažurna i razumljiva dokumentacija.
Anketa
Da bismo procenili kvalitet dokumentacije, odlučili smo da intervjuišemo one koji direktno rade sa njom: analitičare NIB-a. Ispitanici su zamoljeni da procijene 10 tvrdnji prema šemi „Na skali od 1 do 5 (potpuno se ne slažem - potpuno 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 iu potpunosti usklađena sa njihovom implementacijom.
- Implementacija NIB aplikacija je u potpunosti dokumentovana.
- Dokumentacija za NIB aplikacije potrebna je samo za funkcionalnu podršku.
- Dokumentacija za NIB aplikacije je aktuelna u trenutku njihovog podnošenja na funkcionalnu podršku.
- Programeri NIB aplikacija koriste dokumentaciju kako bi razumjeli šta trebaju implementirati.
- Postoji dovoljno dokumentacije za NIB aplikacije da bi se razumjelo kako se implementiraju.
- Aktuelno ažuriram dokumentaciju o NIB projektima ako su finalizirani (od strane mog tima).
- Programeri NIB aplikacija pregledavaju dokumentaciju.
- Jasno razumijem kako pripremiti dokumentaciju za NIB projekte.
- Razumijem kada treba 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 radili kroz korporativni Slack – jednostavno smo poslali poziv sistemskim analitičarima da počnu anketirati. Bilo je 15 analitičara (9 iz Moskve i 6 iz Sankt Peterburga). Nakon što je anketa završena, generirali smo prosječnu ocjenu za svaku od 10 tvrdnji, koju smo potom standardizirali.
Evo šta se desilo.
Istraživanje je pokazalo da iako su analitičari skloni vjerovanju da je implementacija NIB aplikacija u potpunosti dokumentovana, oni ne daju jednoznačnu saglasnost (0.2). Kao konkretan primjer, istakli su da određeni broj baza podataka i redova iz postojećih rješenja nisu obuhvaćeni dokumentacijom. Programer može reći analitičaru da nije sve dokumentirano. Ali teza da programeri pregledavaju dokumentaciju također nije dobila nedvosmislenu podršku (0.33). Odnosno, ostaje rizik nepotpunog opisa implementiranih rješenja.
Relevantnost je lakša - iako opet nema jasnog slaganja (0,13), analitičari su i dalje skloni da dokumentaciju smatraju relevantnom. Komentari su nam omogućili da shvatimo da su problemi s relevantnošću češće na početku nego u sredini. Međutim, nisu nam pisali ništa o podršci.
Što se tiče toga da li sami analitičari razumiju kada je potrebno pisati i ažurirati dokumentaciju, dogovor je bio mnogo ujednačeniji (1,33), uključujući i dizajn (1.07). Ono što je ovdje navedeno kao neugodnost je nedostatak jedinstvenih pravila za vođenje dokumentacije. Stoga, da ne bi uključili režim „Ko ide u šumu, ko dobija ogrev“, oni moraju da rade na osnovu primera postojeće dokumentacije. Stoga je korisna želja kreirati standard za upravljanje dokumentima i razviti šablone za njihove dijelove.
Dokumentacija za NIB aplikacije je aktuelna u trenutku podnošenja za funkcionalnu podršku (0.73). To je razumljivo, jer je jedan od kriterijuma za podnošenje projekta na funkcionalnu podršku ažurna dokumentacija. Također je dovoljno razumjeti implementaciju (0.67), iako ponekad ostaju pitanja.
Ali ono sa čime se ispitanici nisu složili (sasvim jednoglasno) jeste da je dokumentacija za NIB aplikacije, u principu, potrebna samo za funkcionalnu podršku (-1.53). Kao potrošači dokumentacije najčešće su spominjani analitičari. Ostatak tima (programeri) - mnogo rjeđe. Štaviše, analitičari smatraju da programeri ne koriste dokumentaciju da bi razumjeli šta treba implementirati, iako ne jednoglasno (-0.06). To se, inače, očekuje i u uslovima kada se razvoj koda i pisanje dokumentacije odvijaju paralelno.
Šta je suština i zašto su nam ovi brojevi potrebni?
Kako bismo poboljšali kvalitet dokumenata, odlučili smo da učinimo sljedeće:
- Zamolite programera da pregleda pisane dokumente.
- Ako je moguće, ažurirajte dokumentaciju na vrijeme, prije svega.
- Napravite i usvojite standard za dokumentovanje NIB projekata kako bi svi mogli brzo da razumeju koje elemente sistema i kako tačno treba opisati. Pa, razvijte odgovarajuće šablone.
Sve ovo treba da pomogne da se kvalitet dokumenata podigne na novi nivo.
Bar se nadam.
izvor: www.habr.com