Giunsa namo pag-assess ang kalidad sa dokumentasyon

Hello, Habr! Ang akong ngalan mao si Lesha, ako usa ka system analyst alang sa usa sa mga team sa produkto sa Alfa-Bank. Karon nagpalambo ako usa ka bag-ong online nga bangko alang sa mga ligal nga entidad ug indibidwal nga mga negosyante.

Ug kung ikaw usa ka analista, labi na sa ingon nga channel, dili ka makaadto bisan diin kung wala’y dokumentasyon ug suod nga pagtrabaho niini. Ug ang dokumentasyon usa ka butang nga kanunay nagpatunghag daghang mga pangutana. Nganong wala gihulagway ang web application? Ngano nga ang espesipikasyon nagpakita kung giunsa ang serbisyo kinahanglan molihok, apan dili kini molihok nga ingon niana? Ngano nga duha ra ka tawo, ang usa nga nagsulat niini, ang makasabut sa detalye?

Bisan pa, ang dokumentasyon dili mahimong ibalewala sa klaro nga mga hinungdan. Ug aron mas dali ang among kinabuhi, nakahukom kami nga susihon ang kalidad sa dokumentasyon. Giunsa namon kini gibuhat ug kung unsa nga mga konklusyon ang among nahimo sa ubos sa pagputol.

Kalidad sa dokumentasyon

Aron dili masubli ang "Bag-ong Internet Bank" sa daghang dosena nga mga higayon sa teksto, akong isulat ang NIB. Karon kami adunay labaw pa sa usa ka dosena nga mga koponan nga nagtrabaho sa pagpalambo sa NIB alang sa mga negosyante ug ligal nga mga entidad. Dugang pa, ang matag usa kanila nagmugna sa kaugalingon nga dokumentasyon alang sa usa ka bag-ong serbisyo o aplikasyon sa web gikan sa wala, o naghimo mga pagbag-o sa karon. Uban niini nga pamaagi, mahimo ba nga ang dokumentasyon sa prinsipyo adunay taas nga kalidad?

Ug aron mahibal-an ang kalidad sa dokumentasyon, nahibal-an namon ang tulo nga panguna nga mga kinaiya.

1. Kinahanglang kompleto kini. Morag kapitan kini, apan importante nga timan-an. Kinahanglang ihulagway niini sa detalye ang tanang elemento sa gipatuman nga solusyon.
2. Kini kinahanglan nga may kalabutan. Sa ato pa, katumbas sa kasamtangan nga pagpatuman sa solusyon mismo.
3. Kini kinahanglan nga masabtan. Aron ang tawo nga naggamit niini makasabot gayud kung giunsa pagpatuman ang solusyon.

Sa pag-summarize - kompleto, up-to-date ug masabtan nga dokumentasyon.

Poll

Aron masusi ang kalidad sa dokumentasyon, nakahukom kami nga interbyuhon ang mga direktang nagtrabaho niini: mga analista sa NIB. Gihangyo ang mga respondent sa pagtimbang-timbang sa 10 ka pahayag sumala sa laraw "Sa sukod gikan sa 1 hangtod 5 (hingpit nga dili mouyon - hingpit nga mouyon)."

Ang mga pahayag nagpakita sa mga kinaiya sa qualitative documentation ug ang opinyon sa mga survey compiler bahin sa mga dokumento sa NIB.

1. Ang dokumentasyon alang sa mga aplikasyon sa NIB labing bag-o ug hingpit nga nahiuyon sa ilang pagpatuman.
2. Ang pagpatuman sa mga aplikasyon sa NIB hingpit nga dokumentado.
3. Ang dokumentasyon para sa mga aplikasyon sa NIB gikinahanglan lamang para sa functional nga suporta.
4. Ang dokumentasyon para sa mga aplikasyon sa NIB anaa sa panahon sa ilang pagsumite alang sa functional nga suporta.
5. Ang mga nag-develop sa aplikasyon sa NIB naggamit mga dokumentasyon aron masabtan kung unsa ang kinahanglan nila nga ipatuman.
6. Adunay igo nga dokumentasyon alang sa mga aplikasyon sa NIB aron masabtan kung giunsa kini gipatuman.
7. Gi-update dayon nako ang dokumentasyon sa mga proyekto sa NIB kung kini mahuman (sa akong team).
8. Gisusi sa mga developer sa aplikasyon sa NIB ang dokumentasyon.
9. Ako adunay tin-aw nga pagsabut kung giunsa ang pag-andam sa dokumentasyon alang sa mga proyekto sa NIB.
10. Nakasabot ko kung kanus-a magsulat/mag-update sa dokumentasyon para sa mga proyekto sa NIB.

Klaro nga ang yanong pagtubag sa “Gikan sa 1 hangtod 5” mahimong dili magpadayag sa gikinahanglang mga detalye, mao nga ang usa ka tawo makabilin ug komento sa matag butang.

Gibuhat namo kining tanan pinaagi sa corporate Slack - nagpadala lang kami og imbitasyon sa mga system analyst nga magkuha og survey. Adunay 15 ka analista (9 gikan sa Moscow ug 6 gikan sa St. Petersburg). Human makompleto ang survey, nakamugna mi og average score sa matag usa sa 10 ka pahayag, nga among gi-standardize.

Mao ni ang nahitabo.

Gipakita sa survey nga bisan kung ang mga analista hilig sa pagtuo nga ang pagpatuman sa mga aplikasyon sa NIB hingpit nga dokumentado, wala sila maghatag usa ka dili klaro nga kasabutan (0.2). Isip usa ka piho nga pananglitan, ilang gipunting nga daghang mga database ug pila gikan sa kasamtangan nga mga solusyon wala masakop sa dokumentasyon. Ang developer makahimo sa pagsulti sa analista nga dili ang tanan dokumentado. Apan ang thesis nga ang mga developers nagrepaso sa dokumentasyon wala usab makadawat og klaro nga suporta (0.33). Kana mao, ang risgo sa dili kompleto nga paghulagway sa gipatuman nga mga solusyon nagpabilin.

Ang kalambigitan mas sayon ​​- bisan tuod walay klaro nga kasabutan (0,13), ang mga analista hilig gihapon sa pagkonsiderar sa dokumentasyon nga may kalabutan. Ang mga komentaryo nagtugot kanamo nga masabtan nga ang mga problema nga adunay kalabutan mas kanunay sa atubangan kaysa sa tunga. Bisan pa, wala sila nagsulat kanamo bahin sa pagpaluyo.

Sama sa kung ang mga analista mismo nakasabut kung gikinahanglan ang pagsulat ug pag-update sa dokumentasyon, ang kasabutan labi pa nga managsama (1,33), lakip ang disenyo niini (1.07). Ang namatikdan dinhi nga usa ka kahasol mao ang kakulang sa uniporme nga mga lagda alang sa pagpadayon sa dokumentasyon. Busa, aron dili ma-on ang mode nga "Kinsa ang moadto sa lasang, kinsa ang makakuha og sugnod", kinahanglan silang magtrabaho base sa mga pananglitan sa kasamtangan nga dokumentasyon. Busa, usa ka mapuslanon nga pangandoy mao ang paghimo og usa ka sumbanan alang sa pagdumala sa dokumento ug paghimo og mga templates alang sa ilang mga bahin.

Ang dokumentasyon para sa mga aplikasyon sa NIB kay kasamtangan sa panahon sa pagsumite para sa functional nga suporta (0.73). Kini masabtan, tungod kay ang usa sa mga criteria sa pagsumite sa usa ka proyekto alang sa functional nga suporta mao ang pinakabag-o nga dokumentasyon. Igo na usab nga masabtan ang pagpatuman (0.67), bisan pa usahay ang mga pangutana magpabilin.

Apan ang wala uyoni sa mga respondents (medyo nagkahiusa) mao nga ang dokumentasyon alang sa mga aplikasyon sa NIB, sa prinsipyo, gikinahanglan lamang alang sa functional nga suporta (-1.53). Ang mga analista kanunay nga gihisgutan ingon mga konsumedor sa dokumentasyon. Ang nahabilin sa koponan (mga developer) - labi ka dili kaayo kanunay. Dugang pa, ang mga analista nagtuo nga ang mga developers wala mogamit sa dokumentasyon aron masabtan kung unsa ang kinahanglan nilang ipatuman, bisan kung dili nagkahiusa (-0.06). Kini, sa paagi, gilauman usab sa mga kondisyon diin ang pag-uswag sa code ug pagsulat sa dokumentasyon nagpadayon nga managsama.

Unsa ang hinungdan ug ngano nga kinahanglan naton kini nga mga numero?

Aron mapauswag ang kalidad sa mga dokumento, nakahukom kami nga buhaton ang mosunod:

1. Hangyoa ang developer sa pagrepaso sa sinulat nga mga dokumento.
2. Kung mahimo, i-update ang dokumentasyon sa tukma sa panahon nga paagi, una sa atubangan.
3. Paghimo ug pagsagop sa usa ka sumbanan alang sa pagdokumento sa mga proyekto sa NIB aron ang tanan dali nga makasabut kung unsang mga elemento sa sistema ug kung giunsa ang eksakto nga paghulagway. Aw, paghimo ug angay nga mga templates.

Kining tanan makatabang sa pagpataas sa kalidad sa mga dokumento ngadto sa bag-ong lebel.

At least naglaum ko.

Source: www.habr.com