Впрочем, никого не удивить развернутой документацией в разработке, ведущейся по методологии waterfall – так называемому «водопаду». Однако, как показывает практика, подробная документация, составленная специалистами в начале проекта, быстро становится перегруженной и неактуальной, в погоне за излишней детализацией упускается основная цель. В итоге на финальном этапе проекта обновлять громоздкие технические задания некому и незачем: реализация уже очень сильно отличается от того, что было зафиксировано в документе, и, чтобы ее исправить, необходимы значительные трудозатраты. А на подходе новый проект…
А что же делать команде, которая ведет разработку по методологии agile или гибридной методологии, где доработка двигается короткими итерациями, а требования только нарастают, как снежный ком?
Пройдя длительный путь проб и ошибок, мы сформулировали для себя ответы на вопросы:
- Когда и кто формирует документацию на проекте?
- Из чего, в нашем понимании, состоит идеальный документ, который не стыдно отправить клиенту?
- И, наконец, зачем в принципе нужна актуальная документация доработок?
Создание инструкций для пользователей
Одним из очевидных плюсов для наших клиентов стало наличие практически готовой инструкции для пользователей системы, на основе которой можно создать презентацию, вебинар, письменную инструкцию с иллюстрациями в PDF – да что угодно. Особенно приятно, что актуальная логика доработки уже зафиксирована специалистами, которые имели непосредственное отношение к ее созданию: вы не упустите ни одной детали. При желании можно убрать технические тонкости, которые не нужны пользователям, и… Оставить их в инструкции для администраторов.Канал для передачи информации
Любой проект рано или поздно заканчивается, любая команда рано или поздно меняет свой состав. И вот уже прошло несколько лет, и вы захотели внести изменения в свой рабочий процесс, привлекли интегратора или решили самостоятельно провести разработку и… Не обнаружили актуальной документации.На нашей практике такая ситуация встречается у 90% заказчиков, и порой приходится тратить на анализ чужого кода больше времени, чем будет потрачено на «полезные» часы новой доработки. Актуальная и полная документация, безусловно, поможет быстрее войти в курс дела.
Прозрачность процессов
К примеру, вы хотите сделать простую доработку кнопки создания продажи из лида. В интерфейсе системы ничего особенного не происходит, и кажется, что все работает само собой. Но что на самом деле скрывается за нажатием кнопки? Конечно, вы не увидите в документации непонятные куски кода, которые отрабатывают в бэкенде, зато там можно будет найти понятный и простой бизнес-процесс в BPMN-нотации, который объяснит, что происходит на клиентской и сервисной части системы, как именно отрабатывает интеграция, и какие данные откуда берутся в только что созданной продаже.
Пример процесса в нотации BPMN 2.0
Переходя к вопросу о том, кому и когда создавать, а самое главное, поддерживать документацию на проекте, у нас, к сожалению, нет универсального ответа. Большие команды используют для этой цели технических писателей, в малых роли участников проекта могут быть более размыты, и порой несколько человек могут участвовать в создании техзадания.
“Документацию мы начинаем составлять еще на этапе сбора требований: проводим интервью, анализируем, фиксируем, приоритизируем, снова фиксируем.
После согласования первоначальной оценки с заказчиком и передачи задачи в разработку первый вариант документа уже готов. Затем в процессе тестирования и правок в доработке вносятся правки и в документацию.
Финальный вариант ТЗ согласуется с разработчиком, добавляются технические детали и происходит передача заказчику. Количество итераций правок документа напрямую зависит от качественного сбора требований” – Екатерина Косарева, бизнес-аналитик Onellect.
Вот мы и подошли к самой интересной части – из чего же обычно состоит финальный документ, передаваемый заказчику?
Здесь стоит отметить, что выработанная нами концепция не вписывается в общепринятые понятия оформления технической документации по ГОСТ 19 и ГОСТ 34, которые требуются для работы с государственными заказами.
На сегодняшний день наш стандартный проектный документ состоит из следующих частей:
- Суть задачи в формате User story
- Глобальный бизнес-процесс в нотации BPMN 2.0
- ER-диаграммы баз данных, при необходимости
- Пошаговый план реализации для разработчика
- Наполнение и логика для новых объектов
- Изменение логики существующих объектов
- Внедряемые процессы, их отрисовка или описание и характеристика
- Перенос записей и разовые процессы
- Настройка ролевой структуры - Термины и сокращения, принятые на проекте
- Технические детали: пакеты разработки, системные настройки и прочее
- Связь с существующими процессами и доработками
Модель User story
Пример ER-диаграммы базы данных
При этом каждый проект уникален: состав документации меняется, дополняются новые пункты. Если задача совсем небольшая, и для понимания пользователей проще будет посмотреть схему Use case, то почему бы и нет?
Фрагмент Use case
В конце хотелось бы отметить, что мы любим документацию; стремимся к ее дальнейшему совершенствованию и уже давно активно включаем ее в свои процессы разработки.
Актуальная документация значительно облегчает процесс подготовки пользовательских инструкций, заметно сокращает время на изучение ранее сделанных доработок и убирает необходимость вникать в чужой код.