Tere, Habr! Minu nimi on Lesha, olen ühe Alfa-Banki tootemeeskonna süsteemianalüütik. Nüüd töötan välja uut internetipanka juriidilistele isikutele ja üksikettevõtjatele.
Ja kui olete analüütik, eriti sellises kanalis, ei saa te kuhugi ilma dokumentatsioonita ja sellega tihedalt töötada. Ja dokumenteerimine tekitab alati palju küsimusi. Miks veebirakendust ei kirjeldata? Miks on spetsifikatsioonis märgitud, kuidas teenus peaks töötama, aga see ei tööta üldse nii? Miks saavad spetsifikatsioonist aru ainult kaks inimest, kellest üks kirjutas?
Arusaadavatel põhjustel ei saa aga dokumentatsiooni ignoreerida. Ja oma elu lihtsamaks muutmiseks otsustasime hinnata dokumentatsiooni kvaliteeti. Kuidas me seda täpselt tegime ja millistele järeldustele jõudsime, jääb allapoole.
Dokumentatsiooni kvaliteet
Et mitte korduda tekstis mitukümmend korda “Uut internetipanka”, kirjutan NIB-i. Nüüd töötab meil ettevõtjatele ja juriidilistele isikutele mõeldud NIB arendamise kallal üle tosina meeskonna. Lisaks loob igaüks neist nullist uue teenuse või veebirakenduse jaoks oma dokumentatsiooni või teeb praeguses muudatusi. Kas sellise lähenemise korral saab dokumentatsioon põhimõtteliselt kvaliteetne olla?
Ja dokumentatsiooni kvaliteedi määramiseks oleme tuvastanud kolm peamist tunnust.
- See peab olema täielik. See kõlab üsna kapteni moodi, kuid see on oluline tähele panna. See peaks üksikasjalikult kirjeldama kõiki rakendatud lahenduse elemente.
- See peab olema asjakohane. See tähendab, et see vastab lahenduse enda praegusele rakendamisele.
- See peaks olema arusaadav. Et seda kasutav inimene saaks täpselt aru, kuidas lahendust rakendatakse.
Kokkuvõtteks – täielik, ajakohane ja arusaadav dokumentatsioon.
Опрос
Dokumentatsiooni kvaliteedi hindamiseks otsustasime intervjueerida neid, kes sellega otseselt töötavad: NIB analüütikud. Vastajatel paluti hinnata 10 väidet vastavalt skeemile "Skaalal 1-5 (täiesti ei nõustu - täiesti nõus)."
Väited kajastasid kvalitatiivse dokumentatsiooni tunnuseid ja küsitluse koostajate arvamust NIB dokumentide kohta.
- NIB-i rakenduste dokumentatsioon on ajakohane ja nende rakendamisega täielikult kooskõlas.
- NIB rakenduste rakendamine on täielikult dokumenteeritud.
- NIB-rakenduste dokumentatsioon on vajalik ainult funktsionaalseks toeks.
- NIB-i rakenduste dokumentatsioon on nende funktsionaalse toe saamiseks esitamise ajal kehtiv.
- NIB-i rakenduste arendajad kasutavad dokumentatsiooni, et mõista, mida nad peavad juurutama.
- NIB-rakenduste jaoks on piisavalt dokumentatsiooni, et mõista, kuidas neid rakendatakse.
- Värskendan viivitamatult NIB-projektide dokumentatsiooni, kui need on lõpule viidud (minu meeskonna poolt).
- NIB-i rakenduste arendajad vaatavad läbi dokumentatsiooni.
- Mul on selge arusaam, kuidas koostada NIB projektide dokumentatsiooni.
- Ma saan aru, millal kirjutada/uuendada NIB projektide dokumentatsiooni.
On selge, et lihtsalt "1-5" vastamine ei pruugi vajalikke üksikasju paljastada, nii et inimene võib iga üksuse kohta kommentaari jätta.
Tegime seda kõike ettevõtte Slacki kaudu – saatsime süsteemianalüütikutele lihtsalt välja kutse küsitluse läbiviimiseks. Analüütikuid oli 15 (9 Moskvast ja 6 Peterburist). Pärast küsitluse lõpetamist koostasime iga 10 väite kohta keskmise hinde, mille seejärel standardisime.
Nii juhtus.
Uuring näitas, et kuigi analüütikud kalduvad arvama, et NIB rakenduste juurutamine on täielikult dokumenteeritud, ei anna nad üheselt (0.2) nõusolekut. Konkreetse näitena tõid nad välja, et mitmed andmebaasid ja järjekorrad olemasolevatest lahendustest ei olnud dokumentatsiooniga kaetud. Arendaja suudab analüütikule öelda, et kõik pole dokumenteeritud. Kuid ka väitekiri, et arendajad vaatavad läbi dokumentatsiooni, ei saanud ühemõttelist toetust (0.33). See tähendab, et säilib risk, et rakendatud lahendusi kirjeldatakse mittetäielikult.
Asjakohasus on lihtsam – kuigi selget kokkulepet jällegi pole (0,13), kalduvad analüütikud siiski dokumentatsiooni asjakohaseks pidama. Kommentaarid võimaldasid meil mõista, et asjakohasusega seotud probleemid on sagedamini esiküljel kui keskel. Kuid nad ei kirjutanud meile toetamise kohta midagi.
Mis puudutab seda, kas analüütikud ise saavad aru, millal on vaja dokumentatsiooni kirjutada ja uuendada, siis kokkulepe oli palju ühtlasem (1,33), sealhulgas selle kujundus (1.07). Ebameeldivana märgiti siin ühtsete dokumentatsiooni pidamise reeglite puudumist. Seega, et mitte sisse lülitada režiimi “Kes läheb metsa, kes saab küttepuid”, peavad nad töötama olemasoleva dokumentatsiooni näidete põhjal. Seetõttu on kasulik soov luua dokumendihalduse standard ja töötada välja nende osade mallid.
NIB-i taotluste dokumentatsioon on funktsionaalse toe esitamise ajal kehtiv (0.73). See on mõistetav, sest funktsionaalse toetuse projekti esitamise üheks kriteeriumiks on ajakohane dokumentatsioon. Piisab ka teostuse mõistmisest (0.67), kuigi mõnikord jääb küsimusi.
Kuid millega vastajad ei nõustunud (üsna üksmeelselt), oli see, et NIB rakenduste dokumentatsiooni on põhimõtteliselt vaja ainult funktsionaalseks toeks (-1.53). Dokumentatsiooni tarbijatena mainiti kõige sagedamini analüütikuid. Ülejäänud meeskond (arendajad) - palju harvemini. Veelgi enam, analüütikud usuvad, et arendajad ei kasuta dokumentatsiooni, et mõista, mida nad peavad rakendama, kuigi mitte üksmeelselt (-0.06). Seda, muide, eeldatakse ka tingimustes, kus koodiarendus ja dokumentatsiooni kirjutamine käivad paralleelselt.
Mis on lõpptulemus ja miks meil neid numbreid vaja on?
Dokumentide kvaliteedi parandamiseks otsustasime teha järgmist:
- Paluge arendajal kirjalikud dokumendid üle vaadata.
- Võimalusel uuendage dokumentatsiooni õigeaegselt, esiteks.
- Loo ja võta kasutusele standard NIB-projektide dokumenteerimiseks, et igaüks saaks kiiresti aru, milliseid süsteemielemente ja kuidas täpselt kirjeldada tuleks. Noh, töötage välja sobivad mallid.
Kõik see peaks aitama tõsta dokumentide kvaliteeti uuele tasemele.
Vähemalt ma loodan nii.
Allikas: www.habr.com