В небольших и средних проектах, которыми я занимаюсь, мы используем два типа сопроводительной документации:
- Техническое задание (бизнес-описание системы)
- Технический проект (техническое описание системы)
Опционально могут быть добавлены:
- Руководство пользователя
- Руководство администратора
- и другие руководства для каждой должности
Документация преследует следующие цели:
- Обеспечить отчуждаемость программного продукта от команды, уменьшить риски остановки разработки проекта при смене команды.
- Упростить подключение новичков к разработке продукта.
- Упростить процедуру аудита программного продукта и принимаемых проектных решений. По соответствию технических проектных решений техническому заданию и программному коду хорошо видны типовые ошибки в проектировании систем.
- Дать бизнесу возможность понять, что вообще разработали, какие требования предъявлялись к продукту. Нюансы со временем забываются, а новый человек в бизнес-команде всегда сможет поднять техническое задание и почитать, почему продукт работает именно так, а не по другому.
- Управление проектом от документации. Разрозненные задачи зачастую не дают целостного видения проекта, а изменение технического задание перед постановкой задачи дает такое представление.
Основная проблема документации - в ее актуальности. Однажды написанная и не поддерживаемая документация не имеет никакого смысла. Даже техническое задание, написанное на старте, в момент сдачи проекта уже не актуально, так как бизнес всегда вносит коррективы в программный продукт на этапе разработки.
Зачастую на небольших проектах документация разрабатывается под сдачу. То есть в последнюю неделю проекта команда садится и пишет набор документов, формально соответствующих продукту. Несложно догадаться, что:
- Если документация не внедрена в рабочий процесс, то она не будет обновляться в дальнейшем и очень скоро придет в негодность.
- Ценность такой документации даже при непродолжительной ее актуальности не высокая, так как проектные решения там записаны “задним числом”, детали их уже подзабыты.
Поддерживать документацию в актуальном состоянии позволяет внедрение ее обновления в сам процесс разработки программного продукта, а именно:
- Заказчик вместе с менеджером проекта и/или аналитиком обновляют техническое задание на систему.
- Обновление технического задания становится источником информации для эпика и списка задач на следующий этап разработки.
- В процессе работы над задачами разработчики обновляют технический проект.
- После завершения работы над задачами, если результат работы все-таки отличается от изначально предполагаемого, менеджер и/или аналитик вносит изменения в техническое задание по согласованию с заказчиком.
- На основании набора изменений в техническом задании и техническом проекте формируется отчет по релизу и рассылается заинтересованным лицам.
В таком процессе на входе команда разработки имеет целостный документ, который проще согласовать, нежели набор разрозненных задач, а на выходе получает обновленный набор документов и источник для пресс-релиза.
Хорошая документация стоит денег. В целом по часам поддержание в актуальном виде одного типа документа соразмерно с разработкой самого продукта, поэтому поддержка технического проекта практически удваивает затраты времени разработчиков, а для поддержки технического задания в актуальном состоянии в команду вводят аналитика. Написание инструкций пользователя, администратора и т.д. при наличии хорошего актуального технического задания достаточно просто делегируется техническим писателям.