Kaixo, Habr! Nire izena Lesha da, Alfa-Bankeko produktu taldeetako sistema-analista naiz. Orain lineako banku berri bat garatzen ari naiz pertsona juridikoentzat eta banakako ekintzaileentzat.
Eta analista zarenean, batez ere halako kanal batean, ezin zara inora iritsi dokumentaziorik gabe eta harekin lan egin gabe. Eta dokumentazioa beti galdera asko sortzen dituen zerbait da. Zergatik ez da deskribatzen web aplikazioa? Zergatik adierazten du zehaztapenak nola funtzionatu behar duen zerbitzuak, baina ez du batere horrela funtzionatzen? Zergatik da bi pertsonak bakarrik, horietako batek idatzi zuena, uler dezaketela zehaztapena?
Hala ere, dokumentazioa ezin da alde batera utzi arrazoi agerikoengatik. Eta gure bizitza errazteko, dokumentazioaren kalitatea ebaluatzea erabaki genuen. Zehazki nola egin genuen hau eta zer ondoriotara iritsi ginen ebakiaren azpian dago.
Dokumentazioaren kalitatea
Testuan "New Internet Bank" hainbat dozena aldiz ez errepikatzeko, NIB idatziko dut. Orain, dozena bat talde baino gehiago ditugu ekintzaileentzako eta pertsona juridikoentzako NIBaren garapenean lanean. Gainera, bakoitzak bere dokumentazioa sortzen du hutsetik zerbitzu edo web aplikazio berri baterako, edo aldaketak egiten ditu oraingoan. Planteamendu honekin, printzipioz kalitate handiko dokumentazioa izan al daiteke?
Eta dokumentazioaren kalitatea zehazteko, hiru ezaugarri nagusi identifikatu ditugu.
- Osoa izan behar du. Kapitainaren antzekoa dirudi, baina kontuan izan behar da. Inplementatutako irtenbidearen elementu guztiak zehatz deskribatu behar ditu.
- Gaur egungoa izan behar du. Hau da, irtenbidearen beraren egungo ezarpenari dagozkio.
- Ulergarria izan beharko luke. Erabiltzen duenak konponbidea nola ezartzen den zehatz-mehatz uler dezan.
Laburbilduz: dokumentazio osoa, eguneratua eta ulergarria.
ΠΠΏΡΠΎΡ
Dokumentazioaren kalitatea baloratzeko, zuzenean lan egiten dutenei elkarrizketa egitea erabaki dugu: NIBko analistak. Inkestatuei 10 baieztapen ebaluatzeko eskatu zitzaien "1etik 5era (guztiz ados - guztiz ados)" eskemaren arabera.
Adierazpenek dokumentazio kualitatiboaren ezaugarriak eta inkesta-biltzaileen iritzia islatu zituzten NIB dokumentuei buruz.
- NIB aplikazioen dokumentazioa eguneratuta dago eta guztiz koherentea da haien ezarpenarekin.
- NIB aplikazioen ezarpena guztiz dokumentatuta dago.
- NIB aplikazioetarako dokumentazioa euskarri funtzionaletarako soilik behar da.
- NIB aplikazioetarako dokumentazioa eguneratuta dago euskarri funtzionaletarako bidaltzen duten unean.
- NIB aplikazioen garatzaileek dokumentazioa erabiltzen dute inplementatu behar dutena ulertzeko.
- NIB aplikazioak nola inplementatzen diren ulertzeko nahikoa dokumentazio dago.
- NIB proiektuei buruzko dokumentazioa berehala eguneratzen dut, amaitzen badira (nire taldeak).
- NIB aplikazioen garatzaileek dokumentazioa berrikusten dute.
- Argi daukat NIB proiektuetarako dokumentazioa nola prestatu.
- Ulertzen dut NIB proiektuetarako dokumentazioa noiz idatzi/eguneratu.
Argi dago "1etik 5era" erantzuteak agian ez dituela beharrezko xehetasunak agerian utzi, beraz, pertsona batek iruzkin bat utzi dezake elementu bakoitzari.
Hori guztia Slack korporatiboaren bidez egin genuen; besterik gabe, sistemako analistei inkesta bat egiteko gonbidapena bidali genien. 15 analista zeuden (9 Moskukoak eta 6 San Petersburgokoak). Inkesta amaitu ondoren, 10 enuntziatuetako bakoitzaren batez besteko puntuazioa sortu genuen, eta ondoren estandarizatu genuen.
Hau da gertatu dena.
Inkestak erakutsi zuen analistek NIB aplikazioen ezarpena guztiz dokumentatuta dagoela uste duten arren, ez dutela anbiguotasunik gabeko adostasunik ematen (0.2). Adibide zehatz gisa, lehendik zeuden soluzioetako hainbat datu-base eta ilara dokumentazioak ez zituela jaso adierazi zuten. Garatzailea gai da analistari dena ez dagoela dokumentatuta esateko. Baina garatzaileek dokumentazioa berrikusten duten tesiak ere ez zuen inolako laguntzarik jaso (0.33). Hau da, inplementatutako soluzioen deskribapen osatugabea izateko arriskua mantentzen da.
Garrantzitsua errazagoa da - nahiz eta berriro adostasun argirik ez dagoen (0,13), analistek dokumentazioa garrantzitsutzat jotzeko joera dute oraindik. Iruzkinek garrantzia duten arazoak erdialdean baino maizago aurrean daudela ulertu ahal izan dugu. Hala ere, ez ziguten ezer idatzi babesari buruz.
Analistek beraiek dokumentazioa idatzi eta eguneratu behar den noiz ulertzen duten ala ez, akordioa askoz uniformeagoa zen (1,33), diseinua barne (1.07). Hemen eragozpen gisa adierazi zena dokumentazioa mantentzeko arau uniformerik ez izatea izan zen. Horregatik, βNor doa basora, nork hartzen duen egurraβ modua ez aktibatzeko, dagoen dokumentazioaren adibideetan oinarrituta egin behar dute lan. Hori dela eta, nahi erabilgarria dokumentuak kudeatzeko estandar bat sortzea eta haien zatietarako txantiloiak garatzea da.
NIB aplikazioetarako dokumentazioa eguneratuta dago euskarri funtzionala aurkezteko unean (0.73). Ulergarria da, izan ere, euskarri funtzionalerako proiektua aurkezteko irizpideetako bat dokumentazio eguneratua baita. Inplementazioa ulertzea ere nahikoa da (0.67), nahiz eta batzuetan galderak geratzen diren.
Baina inkestatuek ados ez zeudenarekin (nahiko aho batez) izan zen NIB aplikazioetarako dokumentazioa, printzipioz, euskarri funtzionaletarako soilik behar dela (-1.53). Analistak dokumentazioaren kontsumitzaile gisa aipatzen ziren gehienetan. Gainerako taldekoak (garatzaileak) - askoz gutxiagotan. Gainera, analistek uste dute garatzaileek ez dutela dokumentazioa erabiltzen inplementatu behar dutena ulertzeko, aho batez ez bada ere (-0.06). Hori, bide batez, kodearen garapena eta dokumentazioaren idazketa paraleloan egiten diren baldintzetan ere espero da.
Zein da azken emaitza eta zergatik behar ditugu zenbaki hauek?
Dokumentuen kalitatea hobetzeko, honako hau egitea erabaki dugu:
- Eskatu garatzaileari idatzizko dokumentuak berrikusteko.
- Ahal izanez gero, eguneratu dokumentazioa garaiz, aurrena.
- Sortu eta onartu NIB proiektuak dokumentatzeko estandar bat, denek azkar uler dezaten zein sistema-elementu eta zehazki nola deskribatu behar diren. Tira, garatu txantiloi egokiak.
Horrek guztiak dokumentuen kalitatea maila berri batera igotzen lagundu beharko luke.
Hala espero dut behintzat.
Iturria: www.habr.com