1. Главная
  2. Блог Onellect
  3. Полезные статьи
  4. Зачем нужна проектная документация по разработке?

Зачем нужна проектная документация по разработке?

22 июня 2023
1202
Одним из ключевых и болезненных этапов реализации проекта является его документация. Почему болезненных? Чаще всего проектная документация воспринимается как утомительный артефакт, а не часть процесса, и зря – она действительно достойна того, чтобы выделить на нее время в процессе разработки. 

Впрочем, никого не удивить развернутой документацией в разработке, ведущейся по методологии waterfall – так называемому «водопаду». Однако, как показывает практика, подробная документация, составленная специалистами в начале проекта, быстро становится перегруженной и неактуальной, в погоне за излишней детализацией упускается основная цель. В итоге на финальном этапе проекта обновлять громоздкие технические задания некому и незачем: реализация уже очень сильно отличается от того, что было зафиксировано в документе, и, чтобы ее исправить, необходимы значительные трудозатраты. А на подходе новый проект… 

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

Пройдя длительный путь проб и ошибок, мы сформулировали для себя ответы на вопросы: 
  • Когда и кто формирует документацию на проекте? 
  • Из чего, в нашем понимании, состоит идеальный документ, который не стыдно отправить клиенту? 
  • И, наконец, зачем в принципе нужна актуальная документация доработок?  
Начнем с ответа на последний вопрос, чтобы сразу найти мотивацию к документированию проекта, которая порой кажется нудной и рутинной задачей.  

Создание инструкций для пользователей

Одним из очевидных плюсов для наших клиентов стало наличие практически готовой инструкции для пользователей системы, на основе которой можно создать презентацию, вебинар, письменную инструкцию с иллюстрациями в PDF – да что угодно. Особенно приятно, что актуальная логика доработки уже зафиксирована специалистами, которые имели непосредственное отношение к ее созданию: вы не упустите ни одной детали. При желании можно убрать технические тонкости, которые не нужны пользователям, и… Оставить их в инструкции для администраторов. 

Канал для передачи информации

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

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

Прозрачность процессов

К примеру, вы хотите сделать простую доработку кнопки создания продажи из лида. В интерфейсе системы ничего особенного не происходит, и кажется, что все работает само собой. Но что на самом деле скрывается за нажатием кнопки? Конечно, вы не увидите в документации непонятные куски кода, которые отрабатывают в бэкенде, зато там можно будет найти понятный и простой бизнес-процесс в BPMN-нотации, который объяснит, что происходит на клиентской и сервисной части системы, как именно отрабатывает интеграция, и какие данные откуда берутся в только что созданной продаже. 

bpmn.png

Пример процесса в нотации BPMN 2.0 


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

Документацию мы начинаем составлять еще на этапе сбора требований: проводим интервью, анализируем, фиксируем, приоритизируем, снова фиксируем. 

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

Финальный вариант ТЗ согласуется с разработчиком, добавляются технические детали и происходит передача заказчику. Количество итераций правок документа напрямую зависит от качественного сбора требований – Екатерина Косарева, бизнес-аналитик Onellect. 


Вот мы и подошли к самой интересной части – из чего же обычно состоит финальный документ, передаваемый заказчику? 

Здесь стоит отметить, что выработанная нами концепция не вписывается в общепринятые понятия оформления технической документации по ГОСТ 19 и ГОСТ 34, которые требуются для работы с государственными заказами.

На сегодняшний день наш стандартный проектный документ состоит из следующих частей:
  • Суть задачи в формате User story
  • Глобальный бизнес-процесс в нотации BPMN 2.0
  • ER-диаграммы баз данных, при необходимости
  • Пошаговый план реализации для разработчика
    - Наполнение и логика для новых объектов
    - Изменение логики существующих объектов
    - Внедряемые процессы, их отрисовка или описание и характеристика
    - Перенос записей и разовые процессы
    - Настройка ролевой структуры
  • Термины и сокращения, принятые на проекте
  • Технические детали: пакеты разработки, системные настройки и прочее
  • Связь с существующими процессами и доработками

userstory.png

Модель User story


erd.png

Пример ER-диаграммы базы данных


При этом каждый проект уникален: состав документации меняется, дополняются новые пункты. Если задача совсем небольшая, и для понимания пользователей проще будет посмотреть схему Use case, то почему бы и нет?

usecase.png

Фрагмент Use case


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

Актуальная документация значительно облегчает процесс подготовки пользовательских инструкций, заметно сокращает время на изучение ранее сделанных доработок и убирает необходимость вникать в чужой код.
8 (800) 777-31-67