Saluton, Habr! Mi nomiĝas Lesha, mi estas sistemanalizisto por unu el la produktteamoj de Alfa-Banko. Nun mi disvolvas novan retan bankon por juraj entoj kaj individuaj entreprenistoj.
Kaj kiam vi estas analizisto, precipe en tia kanalo, vi ne povas veni ien sen dokumentado kaj proksime labori kun ĝi. Kaj dokumentado estas io, kio ĉiam levas multajn demandojn. Kial la TTT-aplikaĵo ne estas priskribita? Kial la specifo indikas kiel la servo devus funkcii, sed ĝi tute ne funkcias tiel? Kial nur du homoj, el kiuj unu skribis ĝin, povas kompreni la specifon?
Tamen, dokumentaro ne povas esti ignorita pro evidentaj kialoj. Kaj por faciligi nian vivon, ni decidis taksi la kvaliton de dokumentado. Kiel ĝuste ni faris ĉi tion kaj al kiaj konkludoj ni venis estas sub la tranĉo.
Kvalito de dokumentado
Por ne ripeti "Nova Interreta Banko" kelkdek fojojn en la teksto, mi skribos NIB. Nun ni havas pli ol dekduon da teamoj laborantaj pri la disvolviĝo de NIB por entreprenistoj kaj juraj entoj. Plie, ĉiu el ili aŭ kreas sian propran dokumentaron por nova servo aŭ retejo-aplikaĵo de nulo, aŭ faras ŝanĝojn al la nuna. Kun ĉi tiu aliro, ĉu la dokumentaro povas principe esti altkvalita?
Kaj por determini la kvaliton de dokumentado, ni identigis tri ĉefajn trajtojn.
- Ĝi devas esti kompleta. Ĉi tio sonas sufiĉe kiel kapitano, sed gravas noti. Ĝi devus priskribi detale ĉiujn elementojn de la efektivigita solvo.
- Ĝi devas esti aktuala. Tio estas, respondi al la nuna efektivigo de la solvo mem.
- Ĝi devus esti komprenebla. Por ke la uzanto ĝin komprenu ĝuste kiel la solvo estas efektivigita.
Por resumi - kompletan, ĝisdatigitan kaj kompreneblan dokumentadon.
Enketo
Por taksi la kvaliton de la dokumentaro, ni decidis intervjui tiujn, kiuj rekte laboras kun ĝi: NIB-analizistoj. La respondantoj estis petitaj taksi 10 deklarojn laŭ la skemo "Sur skalo de 1 ĝis 5 (tute malkonsentas - tute konsentas)."
La deklaroj reflektis la karakterizaĵojn de kvalita dokumentaro kaj la opinion de la enketkompililoj koncerne NIB-dokumentojn.
- La dokumentaro por la NIB-aplikoj estas ĝisdatigita kaj plene kongrua kun ilia efektivigo.
- La efektivigo de NIB-aplikoj estas plene dokumentita.
- Dokumentado por NIB-aplikoj estas bezonata nur por funkcia subteno.
- Dokumentaro por NIB-aplikoj estas aktuala en la momento de ilia submetado por funkcia subteno.
- NIB-aplikprogramistoj uzas dokumentadon por kompreni kion ili bezonas efektivigi.
- Estas sufiĉe da dokumentaro por la NIB-aplikoj por kompreni kiel ili estas efektivigitaj.
- Mi tuj ĝisdatigas dokumentaron pri NIB-projektoj se ili estas finpretigitaj (de mia teamo).
- NIB-aplikprogramistoj revizias dokumentaron.
- Mi havas klaran komprenon pri kiel prepari dokumentadon por NIB-projektoj.
- Mi komprenas kiam skribi/ĝisdatigi dokumentaron por projektoj de NIB.
Estas klare, ke simple respondi "De 1 ĝis 5" eble ne malkaŝos la necesajn detalojn, do persono povus lasi komenton pri ĉiu objekto.
Ni faris ĉion ĉi per kompania Slack - ni simple sendis inviton al sistemanalizistoj por fari enketon. Estis 15 analizistoj (9 el Moskvo kaj 6 el Sankt-Peterburgo). Post kiam la enketo estis kompletigita, ni generis averaĝan poentaron por ĉiu el la 10 deklaroj, kiujn ni tiam normigis.
Jen kio okazis.
La enketo montris, ke kvankam analizistoj emas kredi, ke la efektivigo de NIB-aplikoj estas plene dokumentita, ili ne donas neambiguan interkonsenton (0.2). Kiel specifa ekzemplo, ili atentigis, ke kelkaj datumbazoj kaj vicoj de ekzistantaj solvoj ne estis kovritaj de dokumentado. La programisto povas diri al la analizisto, ke ne ĉio estas dokumentita. Sed la tezo, ke programistoj revizias dokumentadon ankaŭ ne ricevis senduban subtenon (0.33). Tio estas, la risko de nekompleta priskribo de efektivigitaj solvoj restas.
Graveco estas pli facila - kvankam denove ne ekzistas klara interkonsento (0,13), analizistoj ankoraŭ emas konsideri la dokumentaron trafa. La komentoj permesis al ni kompreni, ke problemoj kun graveco estas pli ofte ĉe la fronto ol en la mezo. Tamen ili skribis nenion al ni pri subteno.
Koncerne ĉu la analizistoj mem komprenas, kiam necesas skribi kaj ĝisdatigi dokumentaron, la interkonsento estis multe pli unuforma (1,33), inkluzive de ĝia dezajno (1.07). Kio estis notita ĉi tie kiel ĝeno estis la manko de unuformaj reguloj por konservi dokumentadon. Tial, por ne ŝalti la reĝimon "Kiu iras al la arbaro, kiu ricevas brullignon", ili devas labori surbaze de ekzemploj de ekzistanta dokumentaro. Tial utila deziro estas krei normon por dokumenta administrado kaj evoluigi ŝablonojn por iliaj partoj.
Dokumentado por NIB-aplikoj estas aktuala en la momento de submetado por funkcia subteno (0.73). Ĉi tio estas komprenebla, ĉar unu el la kriterioj por sendi projekton por funkcia subteno estas ĝisdatigita dokumentado. Sufiĉas ankaŭ kompreni la efektivigon (0.67), kvankam kelkfoje restas demandoj.
Sed pri kio la respondantoj ne konsentis (tute unuanime) estis ke dokumentaro por NIB-aplikoj principe necesas nur por funkcia subteno (-1.53). Analizistoj estis menciitaj plej ofte kiel konsumantoj de dokumentaro. La resto de la teamo (programistoj) - multe malpli ofte. Plie, analizistoj opinias, ke programistoj ne uzas dokumentadon por kompreni, kion ili bezonas efektivigi, kvankam ne unuanime (-0.06). Ĉi tio, cetere, ankaŭ estas atendata en kondiĉoj, kie koda evoluo kaj dokumentado skribas paralele.
Kio estas la fundo kaj kial ni bezonas ĉi tiujn nombrojn?
Por plibonigi la kvaliton de dokumentoj, ni decidis fari la jenon:
- Petu al la programisto revizii skribajn dokumentojn.
- Se eble, ĝisdatigu dokumentaron ĝustatempe, unue.
- Kreu kaj adoptu normon por dokumentado de NIB-projektoj, por ke ĉiuj povu rapide kompreni, kiujn sistemajn elementojn kaj kiel precize oni devas priskribi. Nu, ellaboru taŭgajn ŝablonojn.
Ĉio ĉi devus helpi altigi la kvaliton de dokumentoj al nova nivelo.
Almenaŭ mi esperas tion.
fonto: www.habr.com