Pozdravljeni, Habr! Moje ime je Lesha, sem sistemski analitik za eno od produktnih skupin Alfa-Bank. Sedaj razvijam novo spletno banko za pravne osebe in samostojne podjetnike.
In ko si analitik, sploh v takem kanalu, brez dokumentacije in tesnega dela z njo ne prideš nikamor. In dokumentacija je nekaj, kar vedno poraja veliko vprašanj. Zakaj spletna aplikacija ni opisana? Zakaj je v specifikaciji navedeno, kako naj storitev deluje, pa sploh ne deluje tako? Zakaj samo dve osebi, od katerih je ena napisala, razumeta specifikacijo?
Vendar dokumentacije ni mogoče prezreti iz očitnih razlogov. In da bi si olajšali življenje, smo se odločili oceniti kakovost dokumentacije. Kako natančno smo to storili in do kakšnih zaključkov smo prišli, je spodaj.
Kakovost dokumentacije
Da ne bom v besedilu nekaj desetkrat ponavljal "Nova internetna banka", bom napisal NIB. Zdaj imamo več kot ducat ekip, ki delajo na razvoju NIB za podjetnike in pravne osebe. Poleg tega vsak od njih ustvari lastno dokumentacijo za novo storitev ali spletno aplikacijo iz nič ali spremeni trenutno. Ali je s tem pristopom lahko dokumentacija načeloma kakovostna?
Za določitev kakovosti dokumentacije smo identificirali tri glavne značilnosti.
- Mora biti popolna. To zveni precej kapitansko, vendar je pomembno omeniti. V njem naj bodo podrobno opisani vsi elementi implementirane rešitve.
- Mora biti aktualen. To pomeni, da ustrezajo trenutni izvedbi same rešitve.
- Moralo bi biti razumljivo. Tako da oseba, ki jo uporablja, natančno razume, kako je rešitev implementirana.
Če povzamem – popolna, ažurna in razumljiva dokumentacija.
Опрос
Za oceno kakovosti dokumentacije smo se odločili intervjuvati tiste, ki z njo neposredno delajo: analitike NIB. Anketiranci so bili pozvani, da ocenijo 10 trditev po shemi "Na lestvici od 1 do 5 (popolnoma se ne strinjam - popolnoma se strinjam)."
Izjave so odražale značilnosti kvalitativne dokumentacije in mnenje pripravljavcev ankete o dokumentih NIB.
- Dokumentacija za aplikacije NIB je posodobljena in popolnoma skladna z njihovo implementacijo.
- Implementacija aplikacij NIB je v celoti dokumentirana.
- Dokumentacija za aplikacije NIB je potrebna samo za funkcionalno podporo.
- Dokumentacija za aplikacije NIB je aktualna v času njihove oddaje v funkcionalno podporo.
- Razvijalci aplikacij NIB uporabljajo dokumentacijo, da razumejo, kaj morajo implementirati.
- Obstaja dovolj dokumentacije za aplikacije NIB, da razumemo, kako so implementirane.
- Nemudoma posodobim dokumentacijo o projektih NIB, če so dokončani (s strani moje ekipe).
- Razvijalci aplikacij NIB pregledajo dokumentacijo.
- Jasno razumem, kako pripraviti dokumentacijo za projekte NIB.
- Razumem, kdaj napisati/posodobiti dokumentacijo za projekte NIB.
Jasno je, da preprost odgovor »Od 1 do 5« morda ne razkrije potrebnih podrobnosti, tako da lahko oseba pusti komentar na vsako postavko.
Vse to smo naredili preko korporativnega Slacka – sistemskim analitikom smo preprosto poslali povabilo k anketi. Bilo je 15 analitikov (9 iz Moskve in 6 iz Sankt Peterburga). Po končani anketi smo za vsako od 10 trditev izdelali povprečno oceno, ki smo jo nato standardizirali.
To se je zgodilo.
Raziskava je pokazala, da čeprav se analitiki nagibajo k prepričanju, da je implementacija NIB aplikacij v celoti dokumentirana, ne dajejo nedvoumnega strinjanja (0.2). Kot konkreten primer so izpostavili, da številne baze podatkov in čakalne vrste iz obstoječih rešitev niso dokumentirano pokrite. Razvijalec lahko pove analitiku, da ni vse dokumentirano. A tudi teza, da razvijalci pregledujejo dokumentacijo, ni dobila nedvoumne podpore (0.33). To pomeni, da tveganje nepopolnega opisa implementiranih rešitev ostaja.
Relevantnost je lažja – čeprav spet ni jasnega soglasja (0,13), se analitiki še vedno nagibajo k temu, da je dokumentacija relevantna. Komentarji so nam omogočili razumeti, da so težave z ustreznostjo pogosteje spredaj kot na sredini. O podpori pa nam niso nič napisali.
Glede tega, ali analitiki sami razumejo, kdaj je treba napisati in posodobiti dokumentacijo, je bil dogovor veliko bolj enoten (1,33), tudi njegova zasnova (1.07). Kot nevšečnost so tu izpostavili pomanjkanje enotnih pravil za vodenje dokumentacije. Zato, da ne bi vklopili načina »Kdo gre v gozd, kdo po drva«, morajo delati na podlagi primerov obstoječe dokumentacije. Zato je koristna želja ustvariti standard za upravljanje dokumentov in razviti predloge za njihove dele.
Dokumentacija za aplikacije NIB je aktualna v času oddaje za funkcionalno podporo (0.73). To je razumljivo, saj je eden od kriterijev za oddajo projekta v funkcionalno podporo tudi ažurna dokumentacija. Zadostuje tudi razumevanje izvedbe (0.67), čeprav včasih ostajajo vprašanja.
Anketiranci pa se niso strinjali (precej soglasno), da je dokumentacija za NIB aplikacije načeloma potrebna le za funkcionalno podporo (-1.53). Kot potrošniki dokumentacije so bili največkrat omenjeni analitiki. Preostala ekipa (razvijalci) - veliko redkeje. Poleg tega analitiki menijo, da razvijalci ne uporabljajo dokumentacije, da bi razumeli, kaj morajo implementirati, čeprav ne enotno (-0.06). To je, mimogrede, pričakovano tudi v razmerah, ko razvoj kode in pisanje dokumentacije potekata vzporedno.
Kaj je bistvo in zakaj potrebujemo te številke?
Za izboljšanje kakovosti dokumentov smo se odločili narediti naslednje:
- Prosite razvijalca, da pregleda pisne dokumente.
- Če je mogoče, pravočasno posodobite dokumentacijo, najprej spredaj.
- Ustvarite in sprejmete standard za dokumentiranje projektov NIB, tako da lahko vsakdo hitro razume, katere elemente sistema in kako natančno je treba opisati. No, razvijte ustrezne predloge.
Vse to naj bi pripomoglo k dvigu kakovosti dokumentov na novo raven.
Vsaj upam.
Vir: www.habr.com