Вокруг документации в IT сложились две религии, и обе мне одинаково не нравятся. Первая родом из девяностых: прежде чем написать строку кода, нужно создать двести страниц спецификаций, нарисовать все диаграммы UML, согласовать их с тремя комитетами и подписать. Вторая выросла на гибких методологиях: документация устарела, код и есть документация, работающий продукт важнее бумаг. Первая религия порождает проекты, которые умирают под весом собственных папок. Вторая порождает системы, которые понимает ровно один человек, и когда он уходит, компания остаётся с чёрным ящиком, за который заплатила.
Документация это не бумага, а передача знаний
Я предлагаю посмотреть на вопрос с другой стороны. Документация нужна не ради самой себя и не ради отчётности. Она нужна для одного: чтобы знание о системе существовало не только в чьей-то голове. Головы увольняются, уходят в отпуск, болеют, забывают. А система продолжает жить, и кто-то должен её понимать, исправлять и развивать.
Если смотреть так, то вопрос «нужна ли документация» превращается в вопрос «кому и когда понадобится это знание». И ответ на него почти всегда «нужна, но не вся». Документ, который никто никогда не откроет, бесполезен, сколько бы часов на него ни потратили. Документ, который помог новому разработчику разобраться в системе за день вместо месяца, окупился многократно.
Документация, которая не помогает принимать решения или находить ошибки, это макулатура. Документация, которой нет, когда она нужна, это дыра в бюджете.
Когда UML действительно спасает
UML часто ругают за громоздкость, и в целом справедливо: полный набор его диаграмм для обычного проекта избыточен. Но несколько видов схем я использую постоянно, потому что они экономят часы разговоров.
- Схема данных, то есть какие сущности есть в системе и как они связаны. Это фундамент. Я видел, как спор между отделом продаж и складом о том, что такое «заказ», длившийся неделями, решился за полчаса над одной диаграммой.
- Схема бизнес-процесса: кто, что и в каком порядке делает, где принимаются решения, где возможны отказы. Её понимает не только программист, но и руководитель отдела, и это самое ценное.
- Схема взаимодействия систем, когда в проекте участвуют внешние сервисы, платёжные шлюзы, другие отделы со своими программами. Без неё интеграции превращаются в испорченный телефон.
Отдельно назову три ситуации, когда без документации и схем просто нельзя. Передача проекта новой команде: без описания архитектуры новая команда первые месяцы тратит на археологию. Согласование сложной интеграции между отделами или компаниями: схема становится общим языком, на котором люди с разным бэкграундом договариваются. И проектирование критически важных узлов, где ошибка стоит денег или данных: там схема позволяет найти дыру на бумаге, а не в работающей системе.
Почему документация устаревает и как с этим жить
Главный аргумент противников документации звучит так: она всё равно устаревает. Код меняется каждую неделю, а документ, написанный полгода назад, описывает систему, которой уже нет. И это правда. Устаревшая документация опаснее отсутствующей, потому что она уверенно вводит в заблуждение.
Решение не в том, чтобы отказаться от документации, а в том, чтобы сделать её живой. Документация должна жить рядом с кодом, в том же репозитории, и обновляться в том же изменении, в котором меняется код. Часть её вообще можно генерировать автоматически: схему базы из самой базы, описание API из кода. Тогда она не может устареть по определению.
Мы в Ingello пошли в этом направлении дальше. В Fractal описание системы на наших языках и есть первичный источник: из него генерируется и код, и схема базы, и документация. Описание нельзя «забыть обновить», потому что без его изменения не изменится и сама система. Это, пожалуй, единственный известный мне способ, при котором документация гарантированно соответствует реальности.
Как найти золотую середину
Практическое правило, которым я пользуюсь: документируйте то, что трудно понять из кода, и то, что дорого переделывать. Почему принято именно такое архитектурное решение, а не очевидное другое. Какие ограничения есть у внешних сервисов. Какие бизнес-правила стоят за неочевидной логикой. Как развернуть систему с нуля. А вот описывать словами то, что и так видно из хорошо написанного кода, не нужно, это двойная работа.
И ещё один совет для руководителей: проверьте свою документацию простым тестом. Представьте, что завтра вся команда разработки исчезла. Сможет ли новая команда по тому, что записано, понять, как устроена система, развернуть её и внести изменение? Если ответ «нет», у Вас не система, а заложник.
Что делать завтра
Не начинайте писать документацию на всё. Выберите три вещи: схему данных, схему главного бизнес-процесса и инструкцию по развёртыванию. Если их нет, сделайте. Если есть, проверьте, соответствуют ли они реальности. Договоритесь, что эти документы обновляются вместе с изменениями в коде, и что это часть приёмки задачи.
В Systems мы передаём клиентам системы вместе с живой документацией, а не с папкой, которая устареет к следующему релизу. Потому что система, которую понимает только её автор, принадлежит не Вам, а ему. Документация это способ вернуть себе собственную систему.
