Sveiki, Habr! Mano vardas Lesha, aš esu sistemos analitikas vienoje iš Alfa-Bank produktų komandų. Dabar kuriu naują internetinį banką juridiniams asmenims ir individualiems verslininkams.
O kai esi analitikas, ypač tokiame kanale, be dokumentacijos ir glaudaus darbo su ja niekur nepasieksi. O dokumentacija visada kelia daug klausimų. Kodėl žiniatinklio programa neaprašyta? Kodėl specifikacijoje nurodyta, kaip paslauga turi veikti, bet ji visiškai neveikia? Kodėl tik du žmonės, iš kurių vienas parašė, gali suprasti specifikaciją?
Tačiau dokumentai negali būti ignoruojami dėl akivaizdžių priežasčių. O kad gyvenimas būtų lengvesnis, nusprendėme įvertinti dokumentacijos kokybę. Kaip tiksliai tai padarėme ir kokias išvadas padarėme, yra žemiau.
Dokumentacijos kokybė
Kad tekste nesikartotų keliasdešimt kartų „Naujas interneto bankas“, parašysiu NIB. Dabar turime daugiau nei dešimt komandų, dirbančių kuriant NIB verslininkams ir juridiniams asmenims. Be to, kiekvienas iš jų arba sukuria savo dokumentaciją naujai paslaugai ar žiniatinklio programai nuo nulio, arba keičia esamą. Ar taikant šį metodą dokumentacija iš esmės gali būti aukštos kokybės?
O norėdami nustatyti dokumentacijos kokybę, išskyrėme tris pagrindines charakteristikas.
- Ji turi būti pilna. Tai skamba gana kaip kapitonas, tačiau svarbu atkreipti dėmesį. Jame turėtų būti išsamiai aprašyti visi įgyvendinto sprendimo elementai.
- Tai turi būti aktualu. Tai yra, atitinka dabartinį paties sprendimo įgyvendinimą.
- Tai turėtų būti suprantama. Kad juo besinaudojantis asmuo tiksliai suprastų, kaip sprendimas įgyvendinamas.
Apibendrinant – išsami, naujausia ir suprantama dokumentacija.
Опрос
Norėdami įvertinti dokumentacijos kokybę, nusprendėme apklausti tiesiogiai su ja dirbančius asmenis: NIB analitikus. Respondentų buvo paprašyta įvertinti 10 teiginių pagal schemą „Skalėje nuo 1 iki 5 (visiškai nesutinku – visiškai sutinku).“
Teiginiuose atsispindėjo kokybinės dokumentacijos ypatybės ir apklausos rengėjų nuomonė dėl NIB dokumentų.
- NIB taikomųjų programų dokumentacija yra atnaujinta ir visiškai atitinka jų įgyvendinimą.
- NIB programų įgyvendinimas yra visiškai dokumentuotas.
- NIB taikomųjų programų dokumentacija reikalinga tik funkciniam palaikymui.
- NIB taikomųjų programų dokumentai galioja tuo metu, kai jos pateikiamos funkcinei palaikymui.
- NIB programų kūrėjai naudoja dokumentus, kad suprastų, ką jiems reikia įdiegti.
- Yra pakankamai dokumentų, kad NIB programos suprastų, kaip jos įgyvendinamos.
- Nedelsiant atnaujinu dokumentus apie NIB projektus, jei juos užbaigia (mano komanda).
- NIB programų kūrėjai peržiūri dokumentus.
- Aiškiai suprantu, kaip parengti dokumentaciją NIB projektams.
- Suprantu, kada reikia rašyti/atnaujinti NIB projektų dokumentaciją.
Akivaizdu, kad vien atsakymas „Nuo 1 iki 5“ gali neatskleisti reikalingų detalių, todėl žmogus galėtų palikti komentarą prie kiekvienos punkto.
Visa tai padarėme per įmonės „Slack“ – tiesiog išsiuntėme kvietimą sistemos analitikams atlikti apklausą. Buvo 15 analitikų (9 iš Maskvos ir 6 iš Sankt Peterburgo). Baigę apklausą, sugeneravome kiekvieno iš 10 teiginių vidutinį balą, kurį vėliau standartizavome.
Taip atsitiko.
Apklausa parodė, kad nors analitikai yra linkę manyti, kad NIB taikomųjų programų diegimas yra visiškai dokumentuotas, jie nesutinka vienareikšmiškai (0.2). Kaip konkretų pavyzdį jie nurodė, kad daugelis duomenų bazių ir eilių iš esamų sprendimų nebuvo įtrauktos į dokumentaciją. Kūrėjas gali analitikui pasakyti, kad ne viskas dokumentuota. Tačiau tezė, kad kūrėjai peržiūri dokumentaciją, taip pat nesulaukė vienareikšmiško palaikymo (0.33). Tai reiškia, kad išlieka neišsamaus įgyvendintų sprendimų aprašymo rizika.
Aktualumas lengvesnis – nors ir vėl nėra aiškaus susitarimo (0,13), analitikai vis tiek linkę dokumentaciją laikyti aktualia. Komentarai leido suprasti, kad aktualumo problemos dažniau yra priekyje nei viduryje. Tačiau jie mums nieko nerašė apie paramą.
Kalbant apie tai, ar patys analitikai supranta, kada reikia rašyti ir atnaujinti dokumentaciją, susitarimas buvo daug vienodesnis (1,33), įskaitant jo dizainą (1.07). Kaip nepatogumas čia buvo pastebėtas vienodų dokumentų tvarkymo taisyklių trūkumas. Todėl, kad nebūtų įjungtas režimas „Kas eina į mišką, kas gauna malkų“, jie turi dirbti pagal esamos dokumentacijos pavyzdžius. Taigi naudingas noras yra sukurti dokumentų valdymo standartą ir sukurti jų dalių šablonus.
NIB paraiškų dokumentacija yra aktuali funkcinės paramos pateikimo metu (0.73). Tai suprantama, nes vienas iš kriterijų teikiant projektą funkcinei paramai gauti yra naujausia dokumentacija. Taip pat pakanka suprasti įgyvendinimą (0.67), nors kartais lieka klausimų.
Tačiau su kuo respondentai nesutiko (gana vieningai), kad NIB taikomųjų programų dokumentacija iš esmės reikalinga tik funkcinei palaikymui (-1.53). Kaip dokumentacijos vartotojai dažniausiai buvo minimi analitikai. Likusi komanda (kūrėjai) – daug rečiau. Be to, analitikai mano, kad kūrėjai nesinaudoja dokumentacija, kad suprastų, ką jiems reikia įdiegti, nors ir ne vienbalsiai (-0.06). To, beje, tikimasi ir tokiomis sąlygomis, kai kodo kūrimas ir dokumentacijos rašymas vyksta lygiagrečiai.
Kas yra esmė ir kodėl mums reikia šių skaičių?
Siekdami pagerinti dokumentų kokybę, nusprendėme atlikti šiuos veiksmus:
- Paprašykite kūrėjo peržiūrėti rašytinius dokumentus.
- Jei įmanoma, laiku atnaujinkite dokumentus, pirmiausia priekyje.
- Sukurkite ir pritaikykite NIB projektų dokumentavimo standartą, kad kiekvienas galėtų greitai suprasti, kurie sistemos elementai ir kaip tiksliai turi būti aprašyti. Na, sukurkite tinkamus šablonus.
Visa tai turėtų padėti pakelti dokumentų kokybę į naują lygį.
Bent jau aš taip tikiuosi.
Šaltinis: www.habr.com