Привет, Хабр! Это Евгения Миронова — Senior Business Analyst, Павел Орлов — Senior System Analyst и Мансур Сафиуллин — Middle Business Analyst из МТС Диджитал. Сегодня будем говорить о проектной документации — той самой, в которой так часто «черт ногу сломит». Чтобы читать было интереснее, мы дополнили теорию практикой. Но не спешите тестировать наши советы — сначала дочитайте пост до конца. Поехали!
В чем проблема?
Прежде чем перейти к практическим советам, обсудим, какие две крайности обычно встречаются при реализации проектов, что такое документация в целом, как она составляется и причем тут Agile User Story.
Документации нет вообще vs документации слишком много
Оказывается, выдержать золотую середину не так просто. При реализации проектов часто встречаются две ситуации:
Документации нет совсем. Решение описывается, например, в задачах. Нет систематизированной информации для пользователей и разработчиков. Если нужно что-то посмотреть и уточнить, сделать это просто негде.
Документации слишком много: задокументирована каждая мелочь. И вот когда владелец этих знаний — например, аналитик — переходит на другой проект, оставшиеся участники команды просто теряются. Они сами не могут разобраться и понять, какая документация относится к продукту, какая — к архивной части. Для погружения новых членов команды это тоже проблема: разобрать, как работает система, и начать решать задачи очень трудно.
Сразу отметим: в этой статье мы пишем о «продукте» и о «проекте» как о синонимах. Документация нужна им обоим. Конечно, разница между ними есть, но останавливаться на ней мы сейчас не будем.
Теперь вернемся к причине двух описанных ситуаций. В гибких методологиях разработки не уделяется достаточно внимания и времени качественному документированию. В жизненном цикле разработки нет выделенных этапов, а описывать требования допустимо сразу в задачах. Уже через пару месяцев работы в таком формате найти описание решений и свести их для новых требований будет очень трудно. Поэтому ситуацию нужно исправлять. Как — расскажем дальше, но сначала определимся, что вообще такое документация и что к ней относится.
Что такое документация и как ее составляют?
В первую очередь документация — это бизнес- и функциональные требования. Все, что касается описания функций системы, ее интеграций, методов, взаимосвязи 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. Ведите документацию, не обращая внимания на зрелость продукта
Неважно, зарождается ли ваш продукт, переходит ли он в этап зрелости или он уже зрелый и с легаси — документация всегда ведется одинаково.
Что на самом деле?
Зарождающемуся продукту не нужна детальная документация — здесь важно быстро накидать идеи и перейти к разработке. А вот зрелому продукту, тем более с легаси, без документации не обойтись. Фичей и особенностей может быть так много, что ориентироваться в них без описания будет нереально. А теперь представьте, что в такой ситуации вам нужно решить инциденты — вы просто не поймете, на каком конкретно шаге что-то пошло не так и как все это исправить.
Как это в МТС?
Наша работа с документацией зависит от этапа, на котором находится продукт. Вкратце описать это можно так:
Пока на этом все! Ну что, какой совет возьмете в отработку в первую очередь? ;)
А если серьезно, расскажите, сталкивались ли вы с неудобной документацией? Удалось ли победить этого монстра?