Привіт, Хабре! Мене звуть Льоша, я системний аналітик однієї із продуктових команд Альфа-Банку. Наразі я займаюся розвитком нового інтернет-банку для юридичних осіб та індивідуальних підприємців.
А коли ти аналітик, тим більше у подібному каналі, без документації та щільної роботи з нею – нікуди. І документація це та штука, до якої завжди виникає багато питань. Чому веб-програма не описана? Чому в специфікації зазначено, як має працювати сервіс, а чи працює він взагалі не так? Чому взагалі специфікацію в змозі зрозуміти лише дві особи, одна з яких її написав?
При цьому ігнорувати документацію не можна з очевидних причин. І щоби спростити нам життя, ми вирішили провести оцінку якості документації. Як саме ми це робили і яких висновків дійшли — під катом.
Якість документації
Щоб не повторювати в тексті «Новий інтернет банк» кілька десятків разів, я писатиму НІБ. Зараз у нас над розвитком НІБ для підприємців та юридичних осіб працює понад десяток команд. При цьому кожна з них або з нуля створює свою документацію на новий сервіс або веб-додаток або вносить зміни до поточної. Чи може за такого підходу документація в принципі бути якісною?
І ось визначення якості документації ми виділили три основні характеристики.
- Вона має бути повною. Звучить досить капітанськи, але це важливо відзначити. Вона має докладно описувати всі елементи реалізованого рішення.
- Вона має бути актуальною. Тобто відповідатиме поточній реалізації самого рішення.
- Вона має бути зрозумілою. Щоб людина, яка її використовує, розуміла, як саме реалізовано рішення.
Резюмуючи – повна, актуальна та зрозуміла документація.
Опитування
Щоб оцінити якість документації, ми вирішили опитати тих, хто безпосередньо з нею працює: аналітиків НІБ. Респондентам пропонувалося оцінити 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