Привет, Хабр! Это Евгения Миронова — Senior Business Analyst, Павел Орлов — Senior System Analyst и Мансур Сафиуллин — Middle Business Analyst из МТС Диджитал. Сегодня будем говорить о проектной документации — той самой, в которой так часто «черт ногу сломит». Чтобы читать было интереснее, мы дополнили теорию практическими советами. Но не спешите их тестировать — сначала дочитайте пост до конца. Поехали!

В чем проблема?

Прежде чем перейти к практике, обсудим, какие две крайности обычно встречаются при реализации проектов, что такое документация в целом, как она составляется и причем тут Agile User Story.

Документации нет вообще vs документации слишком много

Оказывается, выдержать золотую середину не так просто. При реализации проектов часто встречаются две ситуации:

1. Документации нет совсем. Решение описывается, например, в задачах. Нет систематизированной информации для пользователей и разработчиков. Если нужно что-то посмотреть и уточнить, сделать это просто негде.

2. Документации слишком много: задокументирована каждая мелочь. И вот когда владелец этих знаний — например, аналитик — переходит на другой проект, оставшиеся участники команды просто теряются. Они сами не могут разобраться и понять, какая документация относится к продукту, какая — к архивной части. Для погружения новых членов команды это тоже проблема: разобрать, как работает система, и начать решать задачи очень трудно.

Сразу отметим: в этой статье мы пишем о «продукте» и о «проекте» как о синонимах. Документация нужна им обоим. Конечно, разница между ними есть, но останавливаться на ней мы сейчас не будем.

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

Что такое документация и как ее составляют?

В первую очередь документация — это бизнес- и функциональные требования. Все, что касается описания функций системы, ее интеграций, методов, взаимосвязи Front- и Back-частей, тест-кейсов. Сюда же относится пользовательская документация.

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

Вести документацию лучше всего по каждой фиче и для разных ролей. Например, Product Owner (PO) интересуют бизнес-требования и то, какие функции системы их реализуют. Системным аналитикам, архитекторам и разработчикам важны описания интеграций, методов, тест-кейсов — и все это во взаимосвязи с функциями системы. Выделенной команде эксплуатации и сопровождения (если она есть на проекте) нужна прозрачная документация, чтобы в любой момент можно было найти конкретный раздел и изучить все, что касается функциональности конкретного приложения.

Владелец продукта и аналитики должны ориентироваться в актуальной информации. Обычно именно у них уточняют, что уже задокументировано, а что только предстоит зафиксировать и реализовать.

Чтобы хорошо вести документацию, нужны User Story

Выше мы уже писали, что отсутствие внимания к осознанному документированию требований в гибких методологиях разработки — это начало проблемы. А сейчас предложим взять хорошую практику из этой методологии, а именно — User Story.

User Story, или пользовательская история, — это способ формулирования потребности пользователя в формате: «Как Х, я хочу Y, чтобы Z». Пример: «Как пользователь системы, я хочу иметь возможность открыть электронную книгу на том месте, где я остановилась в прошлый раз, чтобы продолжить чтение».

Мы предлагаем использовать User Story как единый код для всей сущности по полному циклу разработки — начиная от формулирования требований к архитектурному решению и постановки задачи на разработку до самой разработки, тестирования и создания пользовательской документации. Тогда требования по всему циклу будут связаны.

Такие формулировки вверху страницы позволяют быстро понять, о каких функциях системы пойдет речь ниже. Это поможет сориентироваться в документации и сотруднику, который уже хорошо погружен в продукт, и коллеге из смежной команды, который только начинает с ним знакомиться. Упорядочивание требований по пользовательским историям пригодится и в том случае, если у продукта поменяется владелец.

Чтобы понятно формулировать требования, полезно создавать шаблоны. Например, структура может быть такой:

• общее описание решения;

• цель;

• функциональные возможности;

• Story Map;

• заинтересованные стороны;

• критерии приемки.

Потом на отдельных страницах можно детализировать каждую функциональную возможность. В перспективе — сформировать единый формат требований по компании с увязкой по кодам User Story и тегам, которые позволят объединять требования в одну систему. Эта система должна быть понятна каждому, кто знакомится и работает с ней.

С теорией пока все. Теперь — к практике!

Пять вредных советов, как вести документацию

Совет № 1. Обсуждайте процесс устно — не тратьте время на фиксирование задач 

Соберитесь с командой за круглым столом и распределите задачи между собой. Фиксировать ничего не нужно, ведь вы уже лично обо всем договорились. Просто не тратьте время друг друга.

Что на самом деле?

Павел Орлов: «Как происходит в реальности, можно пояснить на моем примере. В один из проектов я попал на этапе, когда документации было немного. Чтобы сэкономить ресурсы и время, команда обсуждала все устно за круглым столом. Важно отметить, что на этом этапе задачи не формировались — этим занимались уже потом. Дальше следовал этап отстройки процесса. И вот когда задачи для разработчика стали собираться в бэклог, пришло понимание, что документацию нужно было вести сразу. Без нее специалисты не могли оперативно подхватывать задачи, им приходилось отвлекать коллег и задавать вопросы в духе: “Напомните, а что мне здесь нужно было сделать?”»

Как это в МТС?

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

Совет № 2. Не открывайте доступ к документации и не разрешайте редактировать — вдруг все испортят

Доступ к документации должен быть только у владельца продукта! А если кому-нибудь нужно будет внести изменения, пусть напишет ему напрямую или зафиксирует все у себя в ворде на личном компьютере.

Что на самом деле?

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

Как это в МТС?

У нас есть доступ к документации в любое время. К тому же команда может самостоятельно вносить изменения в документацию. Например, аналитик отвечает за наполнение разделов, связанных с требованиями и функциональностью, а архитектор — за архитектурную часть системы. Разработчик может указать технические детали реализации, если это необходимо, а тестировщик — прописать тестовые сценарии.

Совет № 3. Документация должна быть одинаковой для всех сотрудников

Все участники команды должны вести одну и ту же документацию. На роли делить ее необязательно — это долго. Лучше собрать все данные в одном месте.

Что на самом деле?

Представьте ситуацию: кто-то спрашивает у PO, какая у продукта есть функциональность. В этот момент PO нужно быстро сориентироваться в документации. При этом на этапе интеграции продукта с внешними системами ему не нужно знать детальную техническую реализацию. Гораздо важнее для него — описание фичи с бизнесовой точки зрения: «У нас есть фича Х, она помогает решать вопросы Y». И уже после того, как будет принято решение интегрироваться, подключатся технические специалисты. Они будут работать с более детальной документацией.

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

Как это в МТС?

Мансур Сафиуллин: «У нас есть отдельный раздел документации для бизнеса. Он делится на фичи, которые нужно будет выполнить или которые уже выполнены. Дальше системный аналитик описывает, где и какие доработки нужны для этих фичей, размещает ссылки на страницы разработки.

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

Совет № 4. Не проставляйте статусы готовности документов, работ и задач

Проставлять статусы в документации — пустая трата времени. Для этого есть доски — например, Jira. Там видны статусы всех задач.

Что на самом деле?

Участникам команды важно четко понимать, какая функциональность находится в стадии разработки, какая — на этапе тестирования, что уже в продакшне и кто вообще может пользоваться готовыми возможностями. Доски Jira недостаточно: в ней указывается общее описание решения. В команде важно детальное описание функциональности и статуса готовности — для этого больше подходит Confluence.

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

Если не актуализировать документацию, новым участникам команды будет тяжело разобраться, что к чему. На их погружение уйдет больше времени.

С документацией можно работать так же, как с техдолгом. Например, раз в неделю выделять время для актуализации, проходиться по списку фичей, которые стояли в разработке, и обновлять описание реализованной функциональности.

Как это в МТС?

В нашей команде мы используем две удобные точки контроля:

• DoR (Definition of Ready) — критерии, которые нужно выполнить в команде для того, чтобы задачу могли взять в работу;

• DoD (Definition of Done) — критерии, после которых мы считаем, что задача выполнена.

А вот пример, какие критерии мы используем для всех историй бэклога.

DoR:

• история четко сформулирована;

• критерии приемки истории определены;

• команда delivery оценила историю;

• scrum-команда учла результаты и артефакты исследования пользовательского опыта;

• критерии эффективности определены;

• определен ответственный по приемке истории;

• команда может продемонстрировать историю.

DoD:

• история соответствует критериям приемки, PO ее принял;

• ворота качества (quality gates) пройдены;

• продуктовая и техническая документация обновлена;

• regression scope обновлен согласно регламенту;

• нет дефектов приоритета выше Minor.

Кроме DoR и DoD мы используем статусы на страницах в Confluence, чтобы видеть степень готовности документа. И связываем Confluence и Jira, чтобы было понятно, на каком этапе разработки сейчас находится та или иная функциональность.

Совет № 5. Ведите документацию, не обращая внимания на зрелость продукта

Неважно, зарождается ли ваш продукт, переходит ли он в этап зрелости или он уже зрелый и с легаси — документация всегда ведется одинаково.

Что на самом деле?

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

Как это в МТС?

Наша работа с документацией зависит от этапа, на котором находится продукт. Вкратце описать это можно так:

Пока на этом все! Ну что, какой совет возьмете в отработку в первую очередь? ;)

А если серьезно, расскажите, сталкивались ли вы с неудобной документацией? Удалось ли победить этого монстра?