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

Привет, Хабр! Меня зовут Леша, я системный аналитик одной из продуктовых команд Альфа-Банка. Сейчас я занимаюсь развитием нового интернет-банка для юридических лиц и индивидуальных предпринимателей.

А когда ты аналитик, тем более в подобном канале, без документации и плотной работы с ней — никуда. И документация — это та штука, к которой всегда возникает много вопросов. Почему веб-приложение не описано? Почему в спецификации указано, как должен работать сервис, а работает он вообще не так? Почему вообще спецификацию в состоянии понять только два человека, один из которых ее написал?

При этом игнорировать документацию нельзя по очевидным причинам. И чтобы упростить нам жизнь, мы решили провести оценку качества документации. Как именно мы это делали и к каким выводам пришли — под катом.

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

Чтобы не повторять в тексте «Новый интернет банк» несколько десятков раз, я буду писать НИБ. Сейчас у нас над развитием НИБа для предпринимателей и юридических лиц трудится более десятка команд. При этом каждая из них либо с нуля создает свою документацию на новый сервис или веб-приложение, либо вносит изменения в текущую. Может ли при таком подходе документация в принципе быть качественной?

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

1. Она должна быть полной. Звучит довольно по-капитански, но это важно отметить. Она должна подробно описывать все элементы реализованного решения.
2. Она должна быть актуальной. То есть соответствовать текущей реализации самого решения.
3. Она должна быть понятной. Чтобы использующий ее человек понимал, как именно реализовано решение.

Резюмируя — полная, актуальная и понятная документация.

Опрос

Чтобы оценить качество документации, мы решили опросить тех, кто с ней непосредственно работает: аналитиков НИБ. Респондентам предлагалось оценить 10 утверждений по схеме “По шкале от 1 до 5 (полностью не согласен — полностью согласен)”.

Утверждения же отражали характеристики качественной документации и мнение составителей опроса относительно документов НИБ.

1. Документация по приложениям НИБ актуальна и полностью соответствует их реализации.
2. Реализация приложений НИБ полностью задокументирована.
3. Документация по приложениям НИБ нужна только функциональному сопровождению.
4. Документация по приложениям НИБ актуальна на момент их сдачи на функциональное сопровождение.
5. Разработчики приложений НИБ используют документацию, чтобы понять, что им требуется реализовать.
6. Документации по приложениям НИБ достаточно, чтобы понять, как они реализованы.
7. Я своевременно актуализирую документацию по проектам НИБ в случае их доработки (моей командой).
8. Разработчики приложений НИБ проводят ревью документации.
9. Я имею ясное понимание, как оформлять документацию по проектам НИБ.
10. Я понимаю, когда писать/ актуализировать документацию по проектам НИБ.

Понятно, что просто ответ “От 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). Это тоже, кстати, ожидаемо в условиях, когда разработка кода и написание документации идут параллельно.

Что в итоге и зачем нам эти цифры

Чтобы повысить качество документов, мы решили сделать вот что:

1. Просить разработчика ревьюить написанные документы.
2. По возможности своевременно актуализировать документацию, фронт — в первую очередь.
3. Создать и принять стандарт документирования проектов НИБ, чтобы все могли быстро понять, какие элементы систем и как именно надо описывать. Ну и разработать соответствующие шаблоны.

Все это должно помочь поднять качество документов на новый уровень.

По крайней мере, я на это надеюсь.

Источник: habr.com