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

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

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

Међутим, документација се не може занемарити из очигледних разлога. А да бисмо себи олакшали живот, одлучили смо да проценимо квалитет документације. Како смо то тачно урадили и до каквих закључака смо дошли испод реза.

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

Да се ​​у тексту више десетина пута не понавља „Нова интернет банка“, написаћу НИБ. Сада имамо више десетина тимова који раде на развоју НИБ-а за предузетнике и правна лица. Штавише, сваки од њих или креира сопствену документацију за нову услугу или веб апликацију од нуле, или врши измене у постојећој. Може ли оваквим приступом документација у принципу бити квалитетна?

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

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

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

Опрос

Да бисмо проценили квалитет документације, одлучили смо да интервјуишемо оне који са њом директно раде: аналитичаре НИБ-а. Испитаници су замољени да процене 10 тврдњи према шеми „На скали од 1 до 5 (потпуно се не слажем - потпуно се слажем).“

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

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

Јасно је да једноставно одговарање на „Од 1 до 5” можда неће открити потребне детаље, тако да особа може оставити коментар на сваку ставку.

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

Ево шта се догодило.

Истраживање је показало да иако су аналитичари склони да верују да је имплементација НИБ апликација у потпуности документована, они не дају једнозначну сагласност (0.2). Као конкретан пример, истакли су да један број база података и редова из постојећих решења нису обухваћени документацијом. Програмер може рећи аналитичару да није све документовано. Али теза да програмери прегледају документацију такође није добила недвосмислену подршку (0.33). Односно, остаје ризик непотпуног описа имплементираних решења.

Релевантност је лакша – иако опет нема јасне сагласности (0,13), аналитичари су и даље склони да документацију сматрају релевантном. Коментари су нам омогућили да схватимо да су проблеми са релевантношћу чешће на почетку него у средини. Међутим, нису нам писали ништа о подршци.

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

Документација за НИБ апликације је актуелна у тренутку подношења за функционалну подршку (0.73). Ово је разумљиво, јер је један од критеријума за подношење пројекта на функционалну подршку ажурна документација. Такође је довољно разумети имплементацију (0.67), иако понекад остају питања.

Али оно са чиме се испитаници нису сложили (сасвим једногласно) јесте да је документација за НИБ апликације, у принципу, потребна само за функционалну подршку (-1.53). Као потрошачи документације најчешће су помињани аналитичари. Остатак тима (програмери) - много ређе. Штавише, аналитичари сматрају да програмери не користе документацију да би разумели шта треба да имплементирају, иако не једногласно (-0.06). То се, иначе, очекује и у условима када се развој кода и писање документације одвијају паралелно.

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

Да бисмо побољшали квалитет докумената, одлучили смо да урадимо следеће:

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

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

Бар се надам.

Извор: ввв.хабр.цом