Прывітанне, Хабр! Мяне клічуць Лёша, я сістэмны аналітык адной з прадуктовых каманд Альфа-Банка. Цяпер я займаюся развіццём новага інтэрнэт-банка для юрыдычных асоб і індывідуальных прадпрымальнікаў.
А калі ты аналітык, тым больш у падобным канале, без дакументацыі і шчыльнай працы з ёй - нікуды. І дакументацыя - гэта тая штука, да якой заўсёды ўзнікае шмат пытанняў. Чаму вэб-дадатак не апісана? Чаму ў спецыфікацыі пазначана, як павінен працаваць сэрвіс, а працуе ён увогуле не так? Чаму ўвогуле спецыфікацыю ў стане зразумець толькі два чалавекі, адзін з якіх яе напісаў?
Пры гэтым ігнараваць дакументацыю нельга з відавочных прычын. І каб спрасціць нам жыццё, мы вырашылі правесці адзнаку якасці дакументацыі. Як менавіта мы гэта рабілі і да якіх высноваў прыйшлі - пад катом.
Якасць дакументацыі
Каб не паўтараць у тэксце "Новы інтэрнэт банк" некалькі дзясяткаў разоў, я буду пісаць НІБ. Цяпер у нас над развіццём НІБа для прадпрымальнікаў і юрыдычных асоб працуе больш за дзесятак каманд. Пры гэтым кожная з іх або з нуля стварае сваю дакументацыю на новы сэрвіс або вэб-дадатак, або ўносіць змены ў бягучую. Ці можа пры такім падыходзе дакументацыя ў прынцыпе быць якаснай?
І вось для вызначэння якасці дакументацыі мы вылучылі тры асноўныя характарыстыкі.
- Яна мусіць быць поўнай. Гучыць даволі па-капітанску, але важна адзначыць. Яна павінна падрабязна апісваць усе элементы рэалізаванага рашэння.
- Яна мусіць быць актуальнай. Гэта значыць адпавядаць бягучай рэалізацыі самога рашэння.
- Яна мусіць быць зразумелай. Каб які выкарыстоўвае яе чалавек разумеў, як менавіта рэалізавана рашэнне.
Рэзюмуючы - поўная, актуальная і зразумелая дакументацыя.
Апытанне
Каб ацаніць якасьць дакумэнтацыі, мы вырашылі апытаць тых, хто зь ёй непасрэдна працуе: аналітыкаў НДБ. Рэспандэнтам прапаноўвалася ацаніць 10 сцвярджэнняў па схеме "Па шкале ад 1 да 5 (цалкам не згодны - цалкам згодны)".
Сцвярджэнні ж адлюстроўвалі характарыстыкі якаснай дакументацыі і меркаванне складальнікаў апытання адносна дакументаў НІБ.
- Дакументацыя па дадатках НІБ актуальная і поўнасцю адпавядае іх рэалізацыі.
- Рэалізацыя дадаткаў НІБ цалкам задакументаваная.
- Дакументацыя па прыкладаннях НИБ патрэбная толькі функцыянальнаму суправаджэнню.
- Дакументацыя па дадатках НІБ актуальная на момант іх здачы на функцыянальнае суправаджэнне.
- Распрацоўнікі прыкладанняў НІБ выкарыстоўваюць дакументацыю, каб зразумець, што ім трэба рэалізаваць.
- Дакументацыі па дадатках НІБ дастаткова, каб зразумець, як яны рэалізаваны.
- Я своечасова актуалізую дакументацыю па праектах НІБ у выпадку іх дапрацоўкі (маёй камандай).
- Распрацоўнікі прыкладанняў НІБ праводзяць рэўю дакументацыі.
- Я маю яснае разуменьне, як афармляць дакумэнтацыю па праектах НДБ.
- Я разумею, калі пісаць/актуалізаваць дакумэнтацыю па праектах НДБ.
Зразумела, што проста адказ "Ад 1 да 5" мог не раскрыць патрэбныя падрабязнасці, таму чалавек мог пакінуць каментар да кожнага пункта.
Усё гэта мы праводзілі праз карпаратыўны Slack - проста разаслалі сістэмным аналітыкам прапанову прайсці апытанне. Аналітыкаў было 15 чалавек (9 з Масквы і 6 з Санкт-Пецярбурга). Пасля таго як апытанне было завершана, мы сфарміравалі для кожнага з 10 сцвярджэнняў сярэднюю ацэнку, якую потым нарміравалі.
Атрымалася вось што.
Апытанне паказала, што хоць аналітыкі і схіляюцца да таго, што рэалізацыя дадаткаў НІБ задакументаваная цалкам, але адназначнай згоды тут не даюць (0.2). У якасці канкрэтнага прыкладу яны ўказалі на тое, што шэраг баз даных і чэргаў з існуючых рашэнняў дакументацыяй пакрыты не быў. Распрацоўнік у стане падказаць аналітыку, што задакументавана не ўсё. Але тэза аб тым, што распрацоўшчыкі праводзяць рэўю дакументацыі, таксама не атрымаў адназначнай падтрымкі (0.33). Гэта значыць рызыка непаўнаты апісання рэалізаваных рашэнняў захоўваецца.
З актуальнасцю прасцей - хоць адназначнай згоды зноў няма (0,13), аналітыкі ўсё ж схільныя лічыць дакументацыю актуальнай. Каментары дазволілі нам зразумець, што часцей праблемы з актуальнасцю ёсць на фронце, чым на Мідл. Пра бэк нам, праўда, нічога не пісалі.
Наконт таго, ці разумеюць самі аналітыкі, калі трэба пісаць і актуалізаваць дакументацыю, згода была ўжо куды больш адзінай (1,33), у тым ліку яе афармленне (1.07). Што тут адзначылі як нязручнасць, дык гэта адсутнасць адзіных правілаў вядзення дакументацыі. Таму, каб не ўключаць рэжым "Хто ў лес, хто па дровы", ім даводзіцца працаваць на аснове прыкладаў ужо існуючай дакументацыі. Адсюль карысная жаданне - стварыць стандарт вядзення дакументаў, распрацаваць шаблоны іх частак.
Дакументацыя па дадатках НІБ актуальная на момант здачы на функцыянальнае суправаджэнне (0.73). Яно і зразумела, бо адзін з крытэрыяў здачы праекта на функцыянальнае суправаджэнне - гэта актуальная дакументацыя. А яшчэ яна дастатковая для разумення рэалізацыі (0.67), хоць часам і застаюцца пытанні.
А вось з чым апытаныя не пагадзіліся (даволі аднагалосна), дык гэта з тым, што дакументацыя па дадатках НІБ у прынцыпе патрэбная толькі функцыянальнаму суправаджэнню (-1.53). Аналітыкі ў якасці спажыўцоў дакументацыі згадваліся найчасцей. Астатнія члены каманды (распрацоўшчыкі) - куды радзей. Больш за тое, аналітыкі лічаць, што распрацоўшчыкі не выкарыстоўваюць дакументацыю для разумення таго, што ім трэба рэалізаваць, хоць і не аднагалосна (-0.06). Гэта таксама, дарэчы, чакана ва ўмовах, калі распрацоўка кода і напісанне дакументацыі ідуць раўналежна.
Што ў выніку і навошта нам гэтыя лічбы
Каб павысіць якасць дакументаў, мы вырашылі зрабіць вось што:
- Прасіць распрацоўніка ревьюить напісаныя дакументы.
- Па магчымасці своечасова актуалізаваць дакументацыю, фронт - у першую чаргу.
- Стварыць і прыняць стандарт дакумэнтавання праектаў НДБ, каб усе маглі хутка зразумець, якія элементы сістэм і як менавіта трэба апісваць. Ну і распрацаваць якія адпавядаюць шаблоны.
Усё гэта павінна дапамагчы ўзняць якасць дакументаў на новы ўзровень.
Прынамсі, я на гэта спадзяюся.
Крыніца: habr.com