Вопрос о необходимости документации при разработке вызывает много споров. В динамичном мире IT, где изменения стремительны, я часто слышу холиварные обсуждения: а так ли необходима документация?
Кто-то считает, что программный код сам по себе уже исчерпывающая документация. Например, в предыдущей статье про восстановление документации было несколько комментариев с утверждениями, что документацию вести необязательно, достаточно кодовой базы и условного OpenAPI. Но документация только с использованием OpenAPI часто не учитывает нюансы, и её изучение может выглядеть примерно так:
Как я писал в прошлой статье, мне приходилось работать в проектах без документации, после этого у меня сложилось определённое мнение. В этой статье, на основании своего опыта, я опишу аргументы в пользу ведения документации и поддержания её в актуальном состоянии.
Онбординг новых сотрудников
Первое, с чем сталкивается сотрудник, выходя на новую работу — погружение в проект. При этом команда ожидает от сотрудника максимально быстрой адаптации, чтобы переложить часть нагрузки.
Когда аналитик или разработчик приходит в команду, документация значительно сократит время его погружения.
Если документация актуальная, новый член команды быстрее поймёт архитектуру системы, бизнес-требования и процессы и сможет быстрее и качественнее выполнять задачи.
Если новый сотрудник ознакомится с проектом всего за месяц благодаря наличию документации, это сэкономит компании время и ресурсы. Без неё адаптация может занять значительно больше времени.
Отсутствие документации может затянуть адаптацию, что негативно скажется на производительности всей команды. Также некачественный онбординг может привести к расхождению ожидаемого и реального результата, особенно если доработки делают несколько команд.
По моему опыту, онбординг в похожие по сложности и объёму проекты с документацией сокращается в 3-4 раза.
Уменьшение bus-фактора
Документация снижает зависимость от отдельных членов команды и способствует равномерному распределению знаний внутри команды.
В результате, даже если ключевой сотрудник покинет проект, команда сможет продолжать работу без значительных просадок.
Планирование и управление проектом
Наверняка вы сталкивались с тем, что представители бизнеса просят назвать сроки поставки доработок в прод.
С чётко оформленными требованиями и спецификациями команда разработки точнее определит объём работ и разобьёт проект на задачи.
А ещё сможет точнее оценить сроки на каждую задачу и общее время завершения проекта.
Если бизнеса требует строгие дедлайны выхода в прод (например, нужно выпустить фичу раньше конкурентов), документация позволит понять, можно ли с увеличением штата сотрудников ускорить разработку или распараллеливание работ невозможно.
На одном из проектов нам предложили нанять дополнительных людей в команду для «ускорения» реализации фичи, но после анализа документации мы поняли, что невозможно распараллелить работу и новый сотрудник не сократит сроки релиза. Иногда не все понимают, почему дополнительные руки не ускоряют разработку, в этом случае, мне вспоминается аналогия с картинки:
Сайзинг и планирование ресурсов
На начальном этапе разработки документация поможет не только определить объёмы, но и закупить оборудование.
Вы избежите проблемы, когда вы арендуете сервера, не способные выдерживать нагрузку пользователей, а на увеличение ресурсов не заложен бюджет. После запуска в прод ваша нагрузка на приложение вырастет как этот мальчик, а размер сервера останется как его комбинезон:
Уменьшение рисков эксплуатации
Документация снижает риски, связанные с эксплуатацией ПО.
Когда документация чётко описывает процесс разработки и архитектуру системы, команда быстрее реагирует на инциденты, прилетающие с прода. Это особенно важно при высоких требованиях SLA. Без документации поиск бага похож на поиск иголки в стоге сена.
Мне приходилось анализировать баги, прилетающие с прода, когда не было документации на проекте, это не самое простое занятие. Оглядываясь назад, я понимаю, что в этом вопросе мне сильно помогало умение читать код. Без данного навыка поиск инцидентов затянулся бы.
Повышение качества программного обеспечения
Документация значительно упрощает тестирование.
С документацией QA могут составлять различные тест-кейсы. Это не только экономит время, но и снижает вероятность багов, что в итоге повышает качество продукта. Чёткие требования помогут избежать недопонимания между разработчиками и тестировщиками.
Сокращение времени выхода в прод
Актуальная документация может существенно улучшить время выхода доработок в прод (да-да, тот самый Time to market).
Когда у команда есть доступ к чёткой и понятной документации, она может быстрее разрабатывать функционал.
Этот пункт очень важен, чтобы пользователи вашего продукта не чувствовали себя Хатико в ожидании новой фичи.
Итого
На мой взгляд, вышеописанные аргументы подтверждают, что документация упрощает работу команды и минимизирует самые различные риски. В небольших проектах, когда у вас мало интеграций с внешними сервисами, возможно, подробная документация действительно не нужна. С ростом продукта и команды без документации проявятся проблемы, описанные в статье.
Как вы считаете, с какими ещё проблемами может столкнуться команда, если на проекте нет документации? В каких случаях команда может хорошо себя чувствовать без документации? Поделитесь своим мнением и опытом в комментариях.
Статьи, которые могут быть интересны:
Эксперименты на 3,5 квадратах: качнул сетап от «бомж-уровня» до «мини-студии»
Как у нас почти получилось сделать автономного робота для «Битвы Роботов»
Как дизайнеру с помощью макетов оптимизировать процессы и сэкономить время
База об организации процесса разметки: команда, онбординг, метрики
Подписывайтесь на Телеграм-канал Alfa Digital. Рассказываем о работе в IT и Digital, делимся полезными советами, новостями, видео с митапов, краткими выжимками из статей и многим другим, иногда шутим.
Подписывайтесь на блог Альфа-Банка на Хабре, впереди много хороших статей.