Нужна ли документация на проекте?

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

Кто-то считает, что программный код сам по себе уже исчерпывающая документация. Например, в предыдущей статье про восстановление документации было несколько комментариев с утверждениями, что документацию вести необязательно, достаточно кодовой базы и условного OpenAPI. Но документация только с использованием OpenAPI часто не учитывает нюансы, и её изучение может выглядеть примерно так:

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

Онбординг новых сотрудников

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

Когда аналитик или разработчик приходит в команду, документация значительно сократит время его погружения.

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

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

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

По моему опыту, онбординг в похожие по сложности и объёму проекты с документацией сокращается в 3-4 раза.

Уменьшение bus-фактора

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

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

 

Планирование и управление проектом

Наверняка вы сталкивались с тем, что представители бизнеса просят назвать сроки поставки доработок в прод.

С чётко оформленными требованиями и спецификациями команда разработки точнее определит объём работ и разобьёт проект на задачи.

А ещё сможет точнее оценить сроки на каждую задачу и общее время завершения проекта.

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

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

Сайзинг и планирование ресурсов

На начальном этапе разработки документация поможет не только определить объёмы, но и закупить оборудование. 

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

 

Уменьшение рисков эксплуатации

Документация снижает риски, связанные с эксплуатацией ПО.

Когда документация чётко описывает процесс разработки и архитектуру системы, команда быстрее реагирует на инциденты, прилетающие с прода. Это особенно важно при высоких требованиях SLA. Без документации поиск бага похож на поиск иголки в стоге сена.

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

Повышение качества программного обеспечения

Документация значительно упрощает тестирование.

С документацией QA могут составлять различные тест-кейсы. Это не только экономит время, но и снижает вероятность багов, что в итоге повышает качество продукта. Чёткие требования помогут избежать недопонимания между разработчиками и тестировщиками.

 

Сокращение времени выхода в прод

Актуальная документация может существенно улучшить время выхода доработок в прод (да-да, тот самый Time to market).

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

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

 

Итого

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

---

Как вы считаете, с какими ещё проблемами может столкнуться команда, если на проекте нет документации? В каких случаях команда может хорошо себя чувствовать без документации? Поделитесь своим мнением и опытом в комментариях.