Сорванные дедлайны IT-проектов — головная боль многих компаний. Это не только нервы, но и удорожание производства. Мы тоже периодически сталкиваемся с такой проблемой. Моя команда не исключение. Я решил исправить ситуацию и разобраться, где прячется корень зла.
В этой статье расскажу про наш опыт оптимизации работы, а именно, как мы внедрили Documentation First.
Почему мы не успевали сдавать проекты в срок
Наша основная боль была в том, что мы постоянно всё переделывали. Разработчики понимали свою конкретную задачу, но общего контекста не осознавали. То, что казалось очевидным менеджеру, далеко не всегда учитывали программисты. Они думали, что надо просто вывести новый пункт и кнопку покрасить. А на самом деле под капотом надо было сделать еще 100500 правок, чтобы не задеть рядом стоящий функционал или полностью замкнуть кейс. Часто выходило так, что в начале проекта мы жалели времени на детальное продумывание задачи и потом получали "волейбол": разработчики отдавали задачи тестировщикам, те возвращали им обратно… и так снова и снова, долго и мучительно.
Берите плед, что-то вкусное и/или напитки, будем разбираться, почему так происходит и как с этим бороться.
Признаем честно: разработка программного обеспечения — это процесс производства. Какая бы доля творческого подхода ни была, написание ПО больше напоминает сборку изделия на конвейере, чем создание нового шедевра живописи или литературы. Вместо станков — люди, объединенные в четко построенную цепочку. А значит, как и в любом цеху, в разработке программного обеспечения тоже есть узкие места — звенья цепи, которые тормозят все процессы, а, следовательно, и все проекты.
Как мы поняли, что гибкие методологии не работают
Мы пытались внедрять гибкие методологии, но практика показала Agile-семейство не с лучшей стороны — чем более "гибким" становился подход, тем сильнее проявлялись узкие места.
Так происходит потому, что все agile-методологии придерживаясь одних и тех же ценностей приводят к увеличению точек контроля (т.е. частой демонстрации промежуточного результата). Кажется, что вот оно, счастье.
Но на практике это не так, и мы сейчас поймем, почему!
Где кроется истинная проблема: гипотеза
Чтобы заказчик понял, итерацию (результат), надо показать ему замкнутую цепочку. Логи в консоли или div без стилей ему ничего не скажут. Если результат можно разложить на конкретные требования, то всё ок. Но где сложность?
В реальной продуктовой разработке всё должно быть реализовано в существующей кодовой базе/продукте. Следовательно, у нас возникает много условий, связей, требований.
Мы не просто делаем фичу, нам необходимо аккуратно добавить решение новой проблемы в кодовую базу, которая уже решает задачи и имеет свои правила, ограничения и как-то влияет на данные "сбоку".
Если пренебрегать этим, то тестирование заведет 100500 ошибок, а заказчик щедро одарит дополнительными правками ("все равно будете править, тогда и вот это сделайте"). Так, фича стоимостью "5 рублей" становится серьезной доработкой на "50 рублей".
Но это лишь айсберг проблемы. Фича создаст поток ошибок и правок, которые надо "дожать" в короткие сроки. И это не противоречит ценностям Agile. В рамках методологий такой подход является нормой: показываем итерацию, получаем правки, исправляем, а потом снова показываем "полуфабрикат", который продолжает быть проблемой в живом продукте…Начинаются доброски "в последний вагон" перед релизом.
Что мы получаем? Нервы на пределе, сроки сдвинуты, заказчик недоволен, команда выгорела, а ключевые сотрудники подумывают написать заявление на увольнение.
(!) Важно понимать, что в новом продукте эта ситуация будет менее выраженной. Там нет ландшафта, живых клиентов, уже работающего функционала. Ваши итерации ничему не будут мешать и не будут создавать столько проблем.
Основная проблема — понимание реальной сложности доработки. "Ручное TDD" (высокий уровень операционных затрат) усугубляет ситуацию.
Из-за уже имеющейся кодовой базы в месте стыковки с новыми фичами точки отказа появляются, как грибы. А исправления пожирают время разработчиков и тестировщиков, но не приносят нужного результата.
Как так получается? Мы планируем итерацию, а не пытаемся решить всю задачу, следовательно, пренебрегаем анализом дополнительных требований к ней. Они исходят не от заказчика, который о них может не помнить или банально не знать, а от реализации. Именно глубиной анализа итерации мы жертвуем, применяя гибкие методы управления проектами.
Как решить проблему?
Ввести дополнительный шаг, который позволит провести ревью решения до реализации (фактически, проверить ход мыслей). Для этого Брукс в своей книге "Мифический Человекомесяц" предлагает простое решение: перед написанием кода стоит разработать техническую документацию, но не простую, а ту, которую никто не любит делать. В ней обязательно должны быть:
бизнес-результаты прямо по месту доработки,
окружения: взаимосвязи, на что влияет и т.п.,
логические схемы решения и применяемые алгоритмы,
типовые выборки и используемые в них индексы базы данных,
ограничения реализации.
Сегодня такой подход называется Documentation First.
Как встроить написание документации в рабочий процесс типовой команды разработки, используя привычные инструменты
Как оказалось, достаточно просто. Разработка документации — такая же доброска, как и любое изменение кода, ведь лишь малый круг задач требует доработки технической документации в вашей базе знаний (хотя, такое тоже бывает, и мы планируем этим так же заниматься). Рабочий процесс будет выглядеть следующим образом:
Разработчик берется за задачу, изучает её и пишет документацию прямо в файлах проекта, оставляет комментарии по месту планируемых изменений. Описывает алгоритмы, входящие/выходящие контракты и имеющиеся ограничения, проверки и обязательно сценарий, который решает доработка. Именно описанный сценарий — отправная точка для проверки всего остального. Он позволяет ревьюеру проверить логическую цепочку.
Если есть замечания по решению, ревьюер возвращает доброску на доработку документации с комментариями. Разработчик дорабатывает документацию. Проверка повторяется.
Если с решением все хорошо, доброска возвращается с комментарием "делаем".
Как только получили одобрение по решению, начинаем писать код. Не раньше!
После реализации доброска снова уходит на ревью ответственному разработчику.
Мы просто используем привычный для любого разработчика merge-request, что позволяет внедрить Documentation First в любой команде, не сильно меняя привычные процессы.
Что даёт такое решение?
Ожидаемый эффект выглядит привлекательно:
повышаем осознанность доработок,
идентифицируем требования для реализации,
понижаем вовлеченность тестирования в реализацию,
сокращаем количество итераций до готового состояния,
улучшаем уровень документации кодовой базы, то есть снижаем операционные затраты.
А ещё мы упрощаем разработку автотестов, ведь в коде доброски уже есть вся необходимая информация. То же самое касается и доработки статьи в базе знаний: после реализации задачи разработчику достаточно взять комментарии из кода и с минимальными правками перенести их.
Можно предположить, что такой же эффект даст применение BDD-тестов. Но это не так! Тесты не дают возможность провести ревью решения. Они отражают только достижение конкретного результата, который может быть не полным и так же не учитывать часть сценариев.
Чтобы BDD стало полезным инструментом, все равно нужно провести анализ окружения, требований и ограничений и сформировать их как задачу для разработки теста — сначала описать и формализовать задачу (документировать).
Иными словами, нам не избежать разработки документации, если мы хотим решить проблему, описанную выше.
Проблемы внедрения Documentation First
Мотивация к переходу. Любой разработчик будет пытаться не делать так, как вы предлагаете. Он привык работать иначе и в принципе не любит писать документацию... а ещё ему кажется: чем скорее он начнет писать код, тем быстрее решит задачу. Эта проблема будет самой сложной в решении. Советую заранее готовиться спорить и искать аргументы — приводить реальные примеры проблем, которых можно было бы избежать через документацию.
Контроль выполнения. Люди будут пытаться найти причину, почему именно в их случае проще не делать так, как вы хотите. Вам нужно заранее продумать инструменты контроля того, что Documentation First применяется, как задумано. Сделать это нужно до того, как у вас в плане работ появятся первые задачи, которые будут придерживаться этой методологии. Исследуйте инструменты контроля версий, регулярно проверяйте доброски. Это трудно, но постепенно у команды наступит принятие, и выработается привычка.
Система доработки требований. Скорее всего, приведенного способа на основе добросок вам окажется мало. А еще у вас будут отличаться требования для backend и frontend. Для каких-то случаев нужно сделать исключение... вы должны быть открыты к предложениям, а также уточнять требования и дорабатывать вашу "методичку" по Documentation First для вашей команды. Именно тут стоит применить Аgile.
Эти три проблемы придется решить в любом случае, но, скорее всего, вы столкнетесь и со своими, индивидуальными. О них будет интересно почитать в комментариях к материалу — делиться опытом всегда полезно.
Если проявите упорство и не опустите руки, то первые результаты получите достаточно быстро.
Промежуточные итоги: наш опыт
Эту статью я в пишу в сентябре 2025 года. Мы начали внедрять методологию два месяца назад.
В первый месяц начал проверять её на себе и прошел все пять стадий принятия того, что свои задачи я должен также документировать, пусть и в виде промежуточных документов.
С августа мы начали внедрять метод Documentation First в одной из команд направления, а с сентября — распространять методологию по всем командам и параллельно разрабатывать инструкции, которые подойдут нам.
Первый результат: пока не понимаем необходимый объем документации, который нужно делать при таком подходе. На обсуждение этого ушло больше времени, чем на непосредственное написание, но мы справились и смогли определить требования к содержанию на сегодня.
При анализе добросок по задачам получилась следующая картина:
У нас нет ошибок и потерянных бизнес-процессов, а ревью кода для новых компонентов прошло с первого раза (мы нарисовали схему перед разработкой).
По имеющимся ошибкам, которые как раз связаны с оперативностью результата, правки вносятся быстро, а состояние задач по методу Documentation First стало понятнее.
Тестирование не стесняется посмотреть доброску и прочитать написанное и без долгих объяснений получает указания, что проверить.
При доработках backend-методология показывает себя даже лучше, чем на интерфейсе — меньше файлов надо "потрогать", более линейная логика доработок.
И "на закуску"
Могу сказать с полной уверенностью: Documentation First приводит к повышению гарантий качества и не исключает соблюдения ценностей семейства Agile. Документация — это потерянный артефакт в мире гибких методологий. Многие ошибочно ассоциируют работу Брукса с waterfall. Documentation First призван устранить недостатки гибких методологий\фреймворков, снизить риски за счет бюрократизации в нужных местах. Я поговорил с некоторыми командами компании и увидел, что они интуитивно начинали приходить к этому подходу.
Сейчас мы в начале пути внедрения Documentation First. Пока новый подход дается непросто, но потихоньку приносит свои плоды. Предстоит сделать еще очень много: разработать инструкции, начать использовать Documentation First для всех направлений, разработать блок-схемы и т.д. Но даже сейчас можно сказать: методология, которую разработали до всех вариаций Agile, и сегодня прекрасно справляется с проблемами.
Наш эксперимент продолжается. Посмотрим, какие результаты будут через полгода. Обязательно поделюсь итогами в новой статье в блоге Тензора.
