Paano namin tinasa ang kalidad ng dokumentasyon

Hello, Habr! Ang pangalan ko ay Lesha, isa akong systems analyst para sa isa sa mga team ng produkto ng Alfa-Bank. Ngayon ay bumubuo ako ng bagong online na bangko para sa mga legal na entity at indibidwal na negosyante.

At kapag ikaw ay isang analyst, lalo na sa naturang channel, hindi ka makakarating kahit saan nang walang dokumentasyon at malapit na magtrabaho dito. At ang dokumentasyon ay isang bagay na laging nagdudulot ng maraming katanungan. Bakit hindi inilarawan ang web application? Bakit ipinapahiwatig ng detalye kung paano dapat gumana ang serbisyo, ngunit hindi ito gumagana nang ganoon? Bakit dalawang tao lang, isa sa mga nagsulat nito, ang makakaintindi ng specification?

Gayunpaman, hindi maaaring balewalain ang dokumentasyon para sa malinaw na mga kadahilanan. At upang gawing mas madali ang aming buhay, nagpasya kaming suriin ang kalidad ng dokumentasyon. Paano namin ito ginawa at kung anong mga konklusyon ang aming nakuha ay nasa ilalim ng hiwa.

Kalidad ng dokumentasyon

Upang hindi maulit ang "Bagong Internet Bank" ng ilang dosenang beses sa teksto, isusulat ko ang NIB. Ngayon ay mayroon na kaming higit sa isang dosenang mga koponan na nagtatrabaho sa pagbuo ng NIB para sa mga negosyante at legal na entity. Bukod dito, ang bawat isa sa kanila ay maaaring lumikha ng sarili nitong dokumentasyon para sa isang bagong serbisyo o web application mula sa simula, o gumagawa ng mga pagbabago sa kasalukuyan. Sa pamamaraang ito, maaari bang ang dokumentasyon sa prinsipyo ay may mataas na kalidad?

At upang matukoy ang kalidad ng dokumentasyon, natukoy namin ang tatlong pangunahing katangian.

1. Dapat kumpleto ito. Ito ay parang kapitan, ngunit mahalagang tandaan. Dapat nitong ilarawan nang detalyado ang lahat ng elemento ng ipinatupad na solusyon.
2. Ito ay dapat na kasalukuyang. Iyon ay, tumutugma sa kasalukuyang pagpapatupad ng solusyon mismo.
3. Dapat itong maunawaan. Upang ang taong gumagamit nito ay maunawaan nang eksakto kung paano ipinatupad ang solusyon.

Upang ibuod - kumpleto, napapanahon at naiintindihan na dokumentasyon.

Опрос

Upang masuri ang kalidad ng dokumentasyon, nagpasya kaming kapanayamin ang mga direktang nagtatrabaho dito: mga analyst ng NIB. Ang mga respondente ay hiniling na suriin ang 10 mga pahayag ayon sa pamamaraan na "Sa isang sukat mula 1 hanggang 5 (ganap na hindi sumasang-ayon - ganap na sumasang-ayon)."

Ang mga pahayag ay sumasalamin sa mga katangian ng kwalitatibong dokumentasyon at ang opinyon ng mga nagtitipon ng survey tungkol sa mga dokumento ng NIB.

1. Ang dokumentasyon para sa mga aplikasyon ng NIB ay napapanahon at ganap na naaayon sa kanilang pagpapatupad.
2. Ang pagpapatupad ng mga aplikasyon ng NIB ay ganap na dokumentado.
3. Ang dokumentasyon para sa mga aplikasyon ng NIB ay kailangan lamang para sa functional na suporta.
4. Ang dokumentasyon para sa mga aplikasyon ng NIB ay kasalukuyang sa oras ng kanilang pagsusumite para sa functional na suporta.
5. Gumagamit ang mga developer ng application ng NIB ng dokumentasyon upang maunawaan kung ano ang kailangan nilang ipatupad.
6. May sapat na dokumentasyon para sa mga aplikasyon ng NIB upang maunawaan kung paano ipinatupad ang mga ito.
7. Agad kong ina-update ang dokumentasyon sa mga proyekto ng NIB kung ang mga ito ay na-finalize (ng aking team).
8. Sinusuri ng mga developer ng aplikasyon ng NIB ang dokumentasyon.
9. Mayroon akong malinaw na pag-unawa sa kung paano maghanda ng dokumentasyon para sa mga proyekto ng NIB.
10. Naiintindihan ko kung kailan magsulat/mag-update ng dokumentasyon para sa mga proyekto ng NIB.

Malinaw na ang simpleng pagsagot sa "Mula 1 hanggang 5" ay maaaring hindi magbunyag ng mga kinakailangang detalye, kaya maaaring mag-iwan ng komento ang isang tao sa bawat item.

Ginawa namin ang lahat ng ito sa pamamagitan ng corporate Slack - nagpadala lang kami ng imbitasyon sa mga system analyst para kumuha ng survey. Mayroong 15 analyst (9 mula sa Moscow at 6 mula sa St. Petersburg). Matapos makumpleto ang survey, nakabuo kami ng isang average na marka para sa bawat isa sa 10 mga pahayag, na pagkatapos ay na-standardize namin.

Ito ang nangyari.

Ipinakita ng survey na bagama't ang mga analyst ay hilig na maniwala na ang pagpapatupad ng mga aplikasyon ng NIB ay ganap na dokumentado, hindi sila nagbibigay ng malinaw na kasunduan (0.2). Bilang isang tiyak na halimbawa, itinuro nila na ang isang bilang ng mga database at pila mula sa mga umiiral na solusyon ay hindi sakop ng dokumentasyon. Nasasabi ng developer sa analyst na hindi lahat ay dokumentado. Ngunit ang thesis na sinusuri ng mga developer ang dokumentasyon ay hindi rin nakatanggap ng malinaw na suporta (0.33). Iyon ay, ang panganib ng hindi kumpletong paglalarawan ng mga ipinatupad na solusyon ay nananatili.

Ang kaugnayan ay mas madali - bagama't muli ay walang malinaw na kasunduan (0,13), ang mga analyst ay hilig pa rin na isaalang-alang ang dokumentasyong may kaugnayan. Ang mga komento ay nagpapahintulot sa amin na maunawaan na ang mga problema na may kaugnayan ay mas madalas sa harap kaysa sa gitna. Gayunpaman, wala silang isinulat sa amin tungkol sa pag-back.

Kung ang mga analyst mismo ay nauunawaan kung kailan kinakailangan na magsulat at mag-update ng dokumentasyon, ang kasunduan ay mas pare-pareho (1,33), kasama ang disenyo nito (1.07). Ang nabanggit dito bilang isang abala ay ang kakulangan ng pare-parehong mga patakaran para sa pagpapanatili ng dokumentasyon. Samakatuwid, upang hindi i-on ang mode na "Sino ang pumupunta sa kagubatan, na nakakakuha ng panggatong", kailangan nilang magtrabaho batay sa mga halimbawa ng umiiral na dokumentasyon. Samakatuwid, ang isang kapaki-pakinabang na hangarin ay lumikha ng isang pamantayan para sa pamamahala ng dokumento at bumuo ng mga template para sa kanilang mga bahagi.

Ang dokumentasyon para sa mga aplikasyon ng NIB ay kasalukuyang sa oras ng pagsusumite para sa functional na suporta (0.73). Naiintindihan ito, dahil ang isa sa mga pamantayan para sa pagsusumite ng isang proyekto para sa functional na suporta ay napapanahon na dokumentasyon. Sapat din na maunawaan ang pagpapatupad (0.67), bagama't kung minsan ay nananatili ang mga tanong.

Ngunit ang hindi sinang-ayunan ng mga respondent (medyo nagkakaisa) ay ang dokumentasyon para sa mga aplikasyon ng NIB, sa prinsipyo, ay kailangan lamang para sa functional na suporta (-1.53). Ang mga analyst ay madalas na binanggit bilang mga mamimili ng dokumentasyon. Ang natitirang bahagi ng koponan (mga developer) - mas madalas. Bukod dito, naniniwala ang mga analyst na ang mga developer ay hindi gumagamit ng dokumentasyon upang maunawaan kung ano ang kailangan nilang ipatupad, kahit na hindi nagkakaisa (-0.06). Ito, sa pamamagitan ng paraan, ay inaasahan din sa mga kondisyon kung saan ang pagbuo ng code at pagsulat ng dokumentasyon ay nagpapatuloy nang magkatulad.

Ano ang ilalim na linya at bakit kailangan natin ang mga numerong ito?

Upang mapabuti ang kalidad ng mga dokumento, nagpasya kaming gawin ang mga sumusunod:

1. Hilingin sa developer na suriin ang mga nakasulat na dokumento.
2. Kung maaari, i-update ang dokumentasyon sa isang napapanahong paraan, harap muna.
3. Gumawa at magpatibay ng pamantayan para sa pagdodokumento ng mga proyekto ng NIB upang mabilis na maunawaan ng lahat kung aling mga elemento ng system at kung paano eksaktong dapat ilarawan. Buweno, bumuo ng naaangkop na mga template.

Ang lahat ng ito ay dapat makatulong na itaas ang kalidad ng mga dokumento sa isang bagong antas.

At least umaasa ako.

Pinagmulan: www.habr.com