Привет, Хабр! Меня зовут Леша, я системный аналитик одной из продуктовых команд Альфа-Банка.
Сейчас я разрабатываю новый онлайн-банк для юридических лиц и индивидуальных предпринимателей.
А когда ты аналитик, особенно в таком канале, без документации и плотной работы с ней никуда не денешься.
А документация — это то, что всегда вызывает массу вопросов.
Почему не описано веб-приложение? Почему в спецификации указано, как должен работать сервис, а он работает совсем не так? Почему спецификацию могут понять только два человека, один из которых написал? 
Однако документацию нельзя игнорировать по понятным причинам.
И чтобы облегчить себе жизнь, мы решили оценить качество документации.
Как именно мы это сделали и к каким выводам пришли – ниже под катом.
Качество документации
Чтобы не повторять в тексте несколько десятков раз «Новый интернет-банк», буду писать СИБ.Сейчас над разработкой СИБ для предпринимателей и юридических лиц у нас работает более десятка команд. Причём каждый из них либо создаёт с нуля собственную документацию для нового сервиса или веб-приложения, либо вносит изменения в уже существующий.
Может ли при таком подходе документация в принципе быть качественной? И для определения качества документации мы выделили три основные характеристики.
- Оно должно быть полным.
Это звучит довольно по-капитански, но это важно отметить.
В нем должны быть подробно описаны все элементы реализуемого решения.
- Оно должно быть актуальным.
То есть соответствуют текущей реализации самого решения.
- Это должно быть понятно.
Чтобы человек, использующий его, понимал, как именно реализовано решение.
Опрос
Чтобы оценить качество документации, мы решили опросить тех, кто с ней непосредственно работает: аналитиков СИБ.Респондентам предлагалось оценить 10 утверждений по схеме «По шкале от 1 до 5 (совершенно не согласен – полностью согласен)».
В заявлениях отражены характеристики качественной документации и мнение составителей опроса относительно документов СИБ.
- Документация по приложениям NIB актуальна и полностью соответствует их реализации.
- Реализация приложений NIB полностью документирована.
- Документация для приложений NIB необходима только для функциональной поддержки.
- Документация для приложений NIB актуальна на момент их подачи на функциональную поддержку.
- Разработчики приложений NIB используют документацию, чтобы понять, что им нужно реализовать.
- Для приложений NIB имеется достаточно документации, чтобы понять, как они реализованы.
- Я оперативно обновляю документацию по проектам NIB, если они доработаны (моей командой).
- Разработчики приложений NIB просматривают документацию.
- Имею четкое представление о том, как готовить документацию для проектов СИБ.
- Я понимаю, когда писать/обновлять документацию для проектов NIB.
Все это мы делали через корпоративный 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).
Это, кстати, ожидаемо и в условиях, когда разработка кода и написание документации идут параллельно.
В чем суть и зачем нам нужны эти цифры?
Для улучшения качества документов мы решили сделать следующее:- Попросите разработчика просмотреть письменные документы.
- Если возможно, своевременно обновляйте документацию, в первую очередь.
- Создать и принять стандарт документирования NIB-проектов, чтобы каждый мог быстро понять, какие элементы системы и как именно следует описывать.
Что ж, разработайте соответствующие шаблоны.
По крайней мере, я на это надеюсь.
Теги: #Альфа-Банк #Альфа-Лаборатория #Интернет-банк #документация #системный анализ #качество продукта #Исследования и прогнозы в ИТ #Управление продуктом
-
Сохраните Свои Фишки И Получите Автобус!
19 Oct, 24 -
Знаете Ли Вы, Где Сейчас Используется Лисп?
19 Oct, 24 -
Записи Онлайн-Встреч Из Глубинки
19 Oct, 24 -
О Чем Спросить Президента России?
19 Oct, 24
