Како го оценивме квалитетот на документацијата

Здраво, Хабр! Моето име е Леша, јас сум системски аналитичар за еден од производните тимови на Алфа-Банка. Сега развивам нова онлајн банка за правни лица и индивидуални претприемачи.

И кога сте аналитичар, особено во таков канал, не можете да стигнете никаде без документација и блиска работа со неа. А документацијата е нешто што секогаш покренува многу прашања. Зошто веб-апликацијата не е опишана? Зошто спецификацијата покажува како треба да работи услугата, но воопшто не функционира така? Зошто само двајца луѓе, од кои едниот го напишал, можат да ја разберат спецификацијата?

Сепак, документацијата не може да се игнорира од очигледни причини. И за да ни го олесниме животот, решивме да го оцениме квалитетот на документацијата. Како точно го направивме ова и до какви заклучоци дојдовме е под сечењето.

Квалитет на документација

За да не се повторува „Нова интернет банка“ неколку десетици пати во текстот, ќе напишам NIB. Сега имаме повеќе од десетина тимови кои работат на развој на NIB за претприемачи и правни лица. Покрај тоа, секој од нив или креира своја документација за нова услуга или веб-апликација од нула, или прави промени на тековната. Дали со овој пристап, документацијата во принцип може да биде квалитетна?

И за да го одредиме квалитетот на документацијата, идентификувавме три главни карактеристики.

1. Таа мора да биде целосна. Ова звучи прилично капитенско, но важно е да се забележи. Треба детално да ги опише сите елементи на имплементираното решение.
2. Мора да биде релевантно. Односно, одговараат на моменталната имплементација на самото решение.
3. Тоа треба да биде разбирливо. Така што лицето што го користи ќе разбере како точно се спроведува решението.

Да резимираме - комплетна, ажурирана и разбирлива документација.

Опрос

За да го оцениме квалитетот на документацијата, решивме да ги интервјуираме оние кои директно работат со неа: аналитичарите на NIB. Од испитаниците беше побарано да оценат 10 изјави според шемата „На скала од 1 до 5 (целосно не се согласувам - целосно се согласувам).

Изјавите ги одразуваа карактеристиките на квалитативната документација и мислењето на составувачите на анкетата за документите на НИБ.

1. Документацијата за NIB апликациите е ажурирана и целосно конзистентна со нивната имплементација.
2. Имплементацијата на NIB апликациите е целосно документирана.
3. Документација за NIB апликации е потребна само за функционална поддршка.
4. Документацијата за NIB апликациите е актуелна во моментот на нивното поднесување за функционална поддршка.
5. Програмерите на NIB апликации користат документација за да разберат што треба да имплементираат.
6. Има доволно документација за NIB апликациите да разберат како се имплементирани.
7. Навремено ја ажурирам документацијата за проектите на NIB доколку тие се финализирани (од мојот тим).
8. Развивачите на апликации на NIB ја прегледуваат документацијата.
9. Јас имам јасно разбирање за тоа како да подготвувам документација за проектите на НИБ.
10. Разбирам кога да пишувам/ажурирам документација за проектите на NIB.

Јасно е дека едноставното одговарање „Од 1 до 5“ можеби нема да ги открие потребните детали, па едно лице може да остави коментар за секоја ставка.

Сето ова го направивме преку корпоративниот Slack - едноставно испративме покана до системските аналитичари да направат анкета. Имаше 15 аналитичари (9 од Москва и 6 од Санкт Петербург). По завршувањето на истражувањето, генериравме просечна оценка за секоја од 10-те изјави, кои потоа ги стандардизиравме.

Ова е она што се случи.

Истражувањето покажа дека иако аналитичарите се склони да веруваат дека имплементацијата на NIB апликациите е целосно документирана, тие не даваат недвосмислена согласност (0.2). Како конкретен пример посочија дека голем број бази на податоци и редици од постоечките решенија не се опфатени со документација. Инвеститорот може да му каже на аналитичарот дека не е сè документирано. Но, тезата дека програмерите ја прегледуваат документацијата, исто така, не доби недвосмислена поддршка (0.33). Односно, ризикот од нецелосен опис на имплементираните решенија останува.

Релевантноста е полесна - иако повторно нема јасен договор (0,13), аналитичарите сè уште се склони да ја сметаат документацијата релевантна. Коментарите ни овозможија да разбереме дека проблемите со релевантноста се почесто на предната страна отколку на средината. Сепак, тие не ни напишаа ништо за поддршката.

Што се однесува до тоа дали самите аналитичари разбираат кога е неопходно да се пишува и ажурира документацијата, договорот беше многу поуниформа (1,33), вклучувајќи го и неговиот дизајн (1.07). Она што овде беше забележано како непријатност е немањето единствени правила за одржување на документацијата. Затоа, за да не се вклучи режимот „Кој оди во шума, кој добива огревно дрво“, тие мора да работат врз основа на примери на постоечка документација. Оттука, корисна желба е да се создаде стандард за управување со документи и да се развијат шаблони за нивните делови.

Документацијата за NIB апликациите е актуелна во моментот на поднесување за функционална поддршка (0.73). Тоа е разбирливо, бидејќи еден од критериумите за поднесување проект за функционална поддршка е ажурирана документација. Исто така, доволно е да се разбере имплементацијата (0.67), иако понекогаш остануваат прашања.

Но, она со што испитаниците не се согласија (сосема едногласно) е дека документацијата за NIB апликациите, во принцип, е потребна само за функционална поддршка (-1.53). Како корисници на документација најчесто се споменуваа аналитичарите. Остатокот од тимот (програмери) - многу поретко. Покрај тоа, аналитичарите веруваат дека програмерите не користат документација за да разберат што треба да спроведат, иако не едногласно (-0.06). Ова, инаку, се очекува и во услови кога изработката на кодот и пишувањето на документацијата се одвива паралелно.

Која е суштината и зошто ни се потребни овие бројки?

За да го подобриме квалитетот на документите, решивме да го направиме следново:

1. Побарајте од развивачот да ги прегледа пишаните документи.
2. Ако е можно, ажурирајте ја документацијата навремено, прво напред.
3. Создадете и усвоете стандард за документирање на проекти NIB, така што секој може брзо да разбере кои елементи на системот и како точно треба да се опишат. Па, развијте соодветни шаблони.

Сето ова треба да помогне да се подигне квалитетот на документите на ново ниво.

Барем така се надевам.

Извор: www.habr.com