Вопрос о необходимости документации при разработке вызывает много споров. В динамичном мире IT, где изменения стремительны, я часто слышу холиварные обсуждения: а так ли необходима документация?
Кто-то считает, что программный код сам по себе уже исчерпывающая документация. Например, в предыдущей статье про восстановление документации было несколько комментариев с утверждениями, что документацию вести необязательно, достаточно кодовой базы и условного OpenAPI. Но документация только с использованием OpenAPI часто не учитывает нюансы, и её изучение может выглядеть примерно так:
Как я писал в прошлой статье, мне приходилось работать в проектах без документации, после этого у меня сложилось определённое мнение. В этой статье, на основании своего опыта, я опишу аргументы в пользу ведения документации и поддержания её в актуальном состоянии.
Онбординг новых сотрудников
Первое, с чем сталкивается сотрудник, выходя на новую работу — погружение в проект. При этом команда ожидает от сотрудника максимально быстрой адаптации, чтобы переложить часть нагрузки.
Когда аналитик или разработчик приходит в команду, документация значительно сократит время его погружения.
Если документация актуальная, новый член команды быстрее поймёт архитектуру системы, бизнес-требования и процессы и сможет быстрее и качественнее выполнять задачи.
Если новый сотрудник ознакомится с проектом всего за месяц благодаря наличию документации, это сэкономит компании время и ресурсы. Без неё адаптация может занять значительно больше времени.
Отсутствие документации может затянуть адаптацию, что негативно скажется на производительности всей команды. Также некачественный онбординг может привести к расхождению ожидаемого и реального результата, особенно если доработки делают несколько команд.
По моему опыту, онбординг в похожие по сложности и объёму проекты с документацией сокращается в 3-4 раза.
Уменьшение bus-фактора
Документация снижает зависимость от отдельных членов команды и способствует равномерному распределению знаний внутри команды.
В результате, даже если ключевой сотрудник покинет проект, команда сможет продолжать работу без значительных просадок.
Планирование и управление проектом
Наверняка вы сталкивались с тем, что представители бизнеса просят назвать сроки поставки доработок в прод.
С чётко оформленными требованиями и спецификациями команда разработки точнее определит объём работ и разобьёт проект на задачи.
А ещё сможет точнее оценить сроки на каждую задачу и общее время завершения проекта.
Если бизнеса требует строгие дедлайны выхода в прод (например, нужно выпустить фичу раньше конкурентов), документация позволит понять, можно ли с увеличением штата сотрудников ускорить разработку или распараллеливание работ невозможно.
На одном из проектов нам предложили нанять дополнительных людей в команду для «ускорения» реализации фичи, но после анализа документации мы поняли, что невозможно распараллелить работу и новый сотрудник не сократит сроки релиза. Иногда не все понимают, почему дополнительные руки не ускоряют разработку, в этом случае, мне вспоминается аналогия с картинки:
Сайзинг и планирование ресурсов
На начальном этапе разработки документация поможет не только определить объёмы, но и закупить оборудование.
Вы избежите проблемы, когда вы арендуете сервера, не способные выдерживать нагрузку пользователей, а на увеличение ресурсов не заложен бюджет. После запуска в прод ваша нагрузка на приложение вырастет как этот мальчик, а размер сервера останется как его комбинезон:
Уменьшение рисков эксплуатации
Документация снижает риски, связанные с эксплуатацией ПО.
Когда документация чётко описывает процесс разработки и архитектуру системы, команда быстрее реагирует на инциденты, прилетающие с прода. Это особенно важно при высоких требованиях SLA. Без документации поиск бага похож на поиск иголки в стоге сена.
Мне приходилось анализировать баги, прилетающие с прода, когда не было документации на проекте, это не самое простое занятие. Оглядываясь назад, я понимаю, что в этом вопросе мне сильно помогало умение читать код. Без данного навыка поиск инцидентов затянулся бы.
Повышение качества программного обеспечения
Документация значительно упрощает тестирование.
С документацией QA могут составлять различные тест-кейсы. Это не только экономит время, но и снижает вероятность багов, что в итоге повышает качество продукта. Чёткие требования помогут избежать недопонимания между разработчиками и тестировщиками.
Сокращение времени выхода в прод
Актуальная документация может существенно улучшить время выхода доработок в прод (да-да, тот самый Time to market).
Когда у команда есть доступ к чёткой и понятной документации, она может быстрее разрабатывать функционал.
Этот пункт очень важен, чтобы пользователи вашего продукта не чувствовали себя Хатико в ожидании новой фичи.
Итого
На мой взгляд, вышеописанные аргументы подтверждают, что документация упрощает работу команды и минимизирует самые различные риски. В небольших проектах, когда у вас мало интеграций с внешними сервисами, возможно, подробная документация действительно не нужна. С ростом продукта и команды без документации проявятся проблемы, описанные в статье.
Как вы считаете, с какими ещё проблемами может столкнуться команда, если на проекте нет документации? В каких случаях команда может хорошо себя чувствовать без документации? Поделитесь своим мнением и опытом в комментариях.
Комментарии (14)
newintellimouse
18.11.2024 13:54Как только есть внешний заказчик, так без документации и фиксации требований никуда.
Каждое решение в кодовой базе должно быть подтверждено:
текстом в запросе клиента (электронная почта годится, все устные требования — фиксируются текстом и получается подтверждение по почте, что всё верно);
созданным на основе запроса клиента артефактом в документации;
прикреплёнными к документации задачами;
логом изменения документации и задач на основании изменения требований клиента.
Как только этим пренебрегают, начинается игра в русскую рулетку на основании доверия заказчику.
В достаточно крупных компаниях и соседний отдел может выступать в качестве внешнего заказчика.
В большинстве случаев такая работа аналитика только упрощает жизнь разработчикам в каскадной модели разработки и нормально определяет зоны ответственности за работу решения (пока бизнес-требования не переведены в спецификации; не согласованы с заказчиком; и не созданы задачи; работа в дело не берётся; а когда берётся, то косяк в спецификации — это ответственность аналитика, а не разработчика).
Зато в случае перехода к досудебным разбирательствам или судебным прениям наличие оснований у каждого принятого решения очень сильно поможет юристам компании отстоять свою правоту.
Ruslan964 Автор
18.11.2024 13:54Согласен, разработка для внешнего заказчика без документации - опасна
olku
18.11.2024 13:54Автор пришел к целеполаганию:
Документация нужна читателю а не писателю.
Ее объем, вид и язык также зависит от читателя.
Ruslan964 Автор
18.11.2024 13:54Глобально , да - читают документацию чаще, чем пишут (также как и код). Поэтому документация больше для читателя, чем для писателя
Здесь тоже согласен, документаций может быть насколько видов. Например, пользователю системы не нужно знать какие запросы отправляются при нажатии на зелёную кнопочку, но важно чтобы при нажатии на эту кнопочку происходило событие (например, публикация комментария). При этом разработчику важно знать какой запрос должен отправляться при нажатии на ту же самую зелёную кнопочку.
meirinkun
18.11.2024 13:54Так вроде и так понятно, что с документацией лучше чем без нее. Тут же вопрос в том, сколько это будет стоить и какой эффект принесет. И все упорно не хотят складывать и умножать суммы денег и человеко-часов и сравнивать их, ограничиваясь фразами - "ну маленьким документация не нужна, а большим нужна".
Наверное, было бы неплохо определить размер проекта между "маленьким" и "большим" когда документация нужна.
И определить затраты на восставновление документации, когда ее не вели пока росли до среднего размера проекта. Возможно, дешевле организовать ведение документации с самого начала.
Плюс, возможно, есть отрасли проектов где не вести документацию просто нельзя. А есть типы проектов, где документацию вести не нужно или ее сделает сообщество вокруг вашего продукта.
И главное, до всего этого было бы неплохо определить оптимальный/минимальный состав ""документации"", от которой была максимальная польза для облегчения онбординга, тестирования и прочих кейсов использования.
Вот это был бы анализ.
Ruslan964 Автор
18.11.2024 13:54к сожалению, не всем понятно, что с документацией лучше, чем без нее. Как пример, в моей прошлой статье (https://habr.com/ru/companies/alfa/articles/853396/) почитать комментарии, где несколько человек утверждало, что документация не нужна - это породило у меня идею свести аргументы в отдельную статью....
Что касается вашего предложения по анализу зависимости документации от проектов - интересная идея для будущих статей, спасибо)
ViseMoD
18.11.2024 13:54Это не вопрос из разряда бинарных: можно обойтись без документации или нет? В такой постановке сразу читается две крайности, где "справа" - тонны текста и картинок. А дело в необходимом и достаточном наборе артефактов и степени детализации их содержания! Ведь на каком-то проекте хватит user stories + BDD, а на другом нужно готовить ТЗ, ЧТЗ, ТП и далее C4 схемы, набор use cases с sequence diagram, ER диаграммы и т.п.
Ruslan964 Автор
18.11.2024 13:54В целом согласен, объём документации зависит от многих факторов.
Вданной статье был посыл в целом необходимости документации.
Konstantin1978
18.11.2024 13:54Если в компанию приходит глухонемой разработчик, умеющий читать и писать, и он способен сразу начать писать код и приносить пользу, то в такой компании с документацией все в порядке. Если нет, то с документацией беда. Мало компаний способны пройти "тест глухонемым разработчиком" и вот почему: Документация обнуляет много крикливых паразитов на проекте, чья значимость сильно раздута. Эти паразиты не могут этого позволить и поэтому всячески препятсвуют созданию качественной документации.
Konstantin1978
18.11.2024 13:54Отсутствие документации создает доп нагрузку и требования. Дошло до того, что стали требовать софт скилы от технарей!!! Более уродливого сценария сложно было представить!
Ruslan964 Автор
18.11.2024 13:54Про доп нагрузку - полностью поддерживаю. При этом иногда люди, о которых вы писали в предыдущем комментарии или действительно не замечают этого, либо делают вид, что не замечают этого
Про необходимость софт скиллов не могу полностью согласиться, т.к , на мой взгляд, софты важны вне зависимости от наличия/отсутствия документации)
badattech
Agile и полноценная документация вещи противоречащие друг другу.
Поэтому:
- документацию можно и нужно автоматизировать, писать системную документацию к постоянно меняющейся системе руками грех,
- из опыта - удобнее всего когда требования выдаются устно, а аналитик пишет пользовательскую документацию где-то у себя в сторонке,
- API каждого модуля должно быть описано полностью, без этого не будет работать SemVer
Ruslan964 Автор
"...из опыта - удобнее всего когда требования выдаются устно, а аналитик пишет пользовательскую документацию где-то у себя в сторонке..." - удобно, наверное, да, тк можно распараллелить разработку и аналитику.
Но есть нюанс, как говорится.... "Устную постановку задач" часто встречал, но также часто потом это стреляло в ногу, что у разных людей в голове вырисовывалась разная итоговая реализация и аналитика (которая писалась "в сторонке"). Как итог - аналитика выкидывалась в мусорку, тк переделывать код долго==дорого -> что приводит к bus-фактору и остальным пунктам из данной статьи....
Касаемо agile - все хорошо работает, если процесс выстроен, что не всегда получается... здесь, вероятнее всего, проблема именно планирования.
Если грамотно спланировать, то по agile документация отлично работает. Аналитик должен минимум на 1-2 спринта идти впереди команды разработки - сначала делается документация, в последующих спринтах по полноценной документации - пишется код - строго по документации. Если в ходе написания кода разработчик находит неточности (если аналитик ошибся или поленился воспроизвести весь сценарий "вручную" до автоматизации), то уведомляет об этом аналитика и документация актуализируется - таким образом получается и agile работает и документация в проекте актуальная со всеми вытекающими :)