Как оценихме качеството на документацията

Здравей, Хабр! Казвам се Леша, аз съм системен анализатор за един от продуктовите екипи на Alfa-Bank. Сега разработвам нова онлайн банка за юридически лица и индивидуални предприемачи.

А когато си анализатор, особено в такъв канал, не можеш да стигнеш доникъде без документация и тясна работа с нея. А документацията е нещо, което винаги повдига много въпроси. Защо уеб приложението не е описано? Защо спецификацията показва как трябва да работи услугата, но тя изобщо не работи така? Защо само двама души, единият от които го е написал, могат да разберат спецификацията?

Документацията обаче не може да бъде пренебрегната по очевидни причини. И за да улесним живота си, решихме да оценим качеството на документацията. Как точно направихме това и до какви изводи стигнахме е по-долу.

Качество на документацията

За да не повтарям „Нова интернет банка“ няколко десетки пъти в текста, ще напиша NIB. Сега имаме повече от дузина екипи, които работят по разработването на NIB за предприемачи и юридически лица. Освен това всеки от тях или създава собствена документация за нова услуга или уеб приложение от нулата, или прави промени в текущото. С този подход може ли документацията по принцип да бъде качествена?

И за да определим качеството на документацията, идентифицирахме три основни характеристики.

1. Трябва да е пълно. Това звучи доста капитанско, но е важно да се отбележи. Той трябва да описва подробно всички елементи на внедреното решение.
2. Трябва да е подходящо. Тоест съответстват на текущата реализация на самото решение.
3. Трябва да е разбираемо. Така че лицето, което го използва, разбира как точно се прилага решението.

За да обобщим – пълна, актуална и разбираема документация.

Опрос

За да оценим качеството на документацията, решихме да интервюираме тези, които пряко работят с нея: анализаторите на NIB. Анкетираните бяха помолени да оценят 10 твърдения по схемата „По скала от 1 до 5 (напълно несъгласен - напълно съгласен)“.

Изявленията отразяват характеристиките на качествената документация и мнението на съставителите на проучването относно документите на NIB.

1. Документацията към NIB приложенията е актуална и напълно съобразена с тяхното внедряване.
2. Внедряването на NIB приложения е напълно документирано.
3. Документацията за NIB приложения е необходима само за функционална поддръжка.
4. Документацията за NIB приложения е актуална към момента на подаването им за функционална поддръжка.
5. Разработчиците на приложения на NIB използват документация, за да разберат какво трябва да внедрят.
6. Има достатъчно документация за приложенията на NIB, за да разберете как се изпълняват.
7. Актуализирам незабавно документацията за проекти на NIB, ако са финализирани (от моя екип).
8. Разработчиците на приложения на NIB преглеждат документацията.
9. Имам ясно разбиране как да подготвям документация за проекти на NIB.
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