Или почему техническая документация заслуживает CI/CD не меньше, чем ваш любимый микросервис

Что такое doc as code?

Это подход к документации, в котором вы работаете с ней как с программным кодом:

• используете систему контроля версий (чаще всего — git);
• храните документы в виде простых текстовых файлов (чаще всего — Markdown);
• редактируете в любом редакторе или IDE;
• ревьюите через pull requests;
• автоматически собираете и публикуете (CI/CD);
• тестируете валидность (линтеры, broken links, структура).

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

Зачем это вообще нужно?

Переход на doc as code может решить сразу несколько проблем:

1. Документация устаревает — потому что её ведут отдельно от кода.
2. Её сложно обновлять — потому что она где-то в Confluence, а доступ к нему есть не у всех.
3. Невозможно понять, кто и зачем что-то изменил — без истории версий и контекста коммита.
4. Нет согласованного формата — каждый пишет как хочет, в чём хочет, куда хочет.

С doc as code документация:

✅ Всегда рядом с кодом

✅ Обновляется по тем же процессам, что и код

✅ Проверяется автоматически

✅ Видна всем, у кого есть доступ к репозиторию

✅ Прозрачна и воспроизводима

Как это работает на практике?

Один из популярных стеков для doc as code:

• Markdown — формат файлов.
• MkDocs / Docusaurus / Sphinx — генераторы статических сайтов из Markdown.
• Git — контроль версий, pull requests, ревью.
• GitHub Actions / GitLab CI — автосборка и деплой документации.
• Netlify / GitHub Pages / внутренний сервер — хостинг.

Пример: вы добавили новую фичу — обновили README.md и api_reference.md в той же ветке. При мёрже всё прогоняется через линтеры и автоматически публикуется на docs.myproject.dev.

На что обратить внимание при внедрении:

Выберите инструменты под свою команду

Не всем нужен Sphinx с reStructuredText. Иногда достаточно MkDocs и пары плагинов.

• Определите структуру и правила.

Например: как называть файлы, где хранить картинки, в каком формате писать API, кто отвечает за ревью.

• Обучите команду.

Проведите воркшоп или напишите гайд: как писать, где смотреть результат, как поднять доку локально.

• Интегрируйте в CI/CD.

Даже простой build+link check уже даст пользу.

• Не забывайте про читателя.

Документация — не просто артефакт, а рабочий инструмент. Пишите для людей, а не для галочки.

Когда это особенно полезно:

• Вы делаете SDK или API: тогда дока обязана меняться вместе с кодом.
• У вас open source: сообщество хочет делать pull requests и в код, и в текст.
• Вы устали от Confluence, где ничего не ищется и никто не пишет.
• Вы хотите встроить документацию в процесс разработки, а не вести её параллельно.
• У вас несколько микросервисов, и нужна единая точка входа и общий стиль.

Итого

• Подход doc as code делает документацию живой, актуальной и версионируемой, упрощает ревью, снижает барьер на вход для разработчиков, встраивает работу с текстами в ежедневную рутину команды.

А ещё это просто приятно — когда документация не отстаёт от продукта, а идёт с ним в одной ветке.

Дано: подготовка к важному спецпроекту, этап разработки концепции. Команда общается с инженерами разных профессий, чтобы выделить все ключевые ценности и особенности каждого направления. Это важно для понимания специфики их работы именно в Газпромбанке и ее отражения в брендинге.

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

Кульминация: после встречи с системными аналитиками у меня на руках оказываются заметки для сверки. Просматриваю их по диагонали: всё выглядит в целом верно, а потому отправляю их активистам сообщества на уточнение. Важно было посмотреть, стоит ли добавить деталей или улучшить формулировки. В этот момент обсуждение неожиданно оживляется: в заметках «docs as code» превратилось в «дог ас кот». Сначала это вызвало улыбки и лёгкое недоумение, но быстро стало поводом для шуток. Правки, конечно, внесли, но сама находка уже успела закрепиться в памяти и остаться с нами надолго.

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

Что получилось: шутки, встроенные в доклады о документации, вселили уверенность в том, что всё сработает. Мы с командой HOPов системного анализа (Head of profession, так мы называем лидеров компетенций по каждой из профессий в банке) придумали идею для митапа, где можно было поговорить о темах, которые действительно волнуют команды разработки, рассказать о полезных подходах и создать при этом теплую атмосферу, которая напомнит об этой уже устоявшейся в сообществе игре слов. Поэтому 29 августа у нас прошел митап «Всё as code», обладающий собственным символом: стильным мопсом, который очень старался притвориться котом. Каждая деталь, от образа до мерча и экспертизы, сложилась в яркую и запоминающуюся историю, отражающую наш подход к разработке продукта.

Мораль: культура ошибок — инструмент, который позволяет находить неординарные и инновационные решения, о которых прежде никто не мог подумать. Толерантность к ситуациям, когда на первый взгляд всё идет наперекосяк очень важна в любой работе, особенно с людьми. Примеры из истории показывают это особенно хорошо: пенициллин, появившийся благодаря случайности, микроволновка, родившаяся из эксперимента, и путь Колумба в Америку, доказывают, что из небольших «сбоев» можно извлечь по-настоящему ценные результаты.

Давайте знакомиться! Рассказ будет вестись от лица двух дата-сайентисток — Марии Мичуриной и Ксении Белозёровой.

Находка 1: Планирование поездок с помощью нейросети

Я очень люблю спонтанные поездки на машине — для меня это всегда приключение! Вот только есть один нюанс: терпеть не могу тратить часы на составление маршрутов. Но однажды, после долгого и нудного копания в тревел-статьях, я подумала: «А почему бы не делегировать эту задачу нейросети?» Так я и сделала, проверив эту идею на поездке в Звенигород.

Пример моего запроса для DeepSeek:

Его ответ:

Мне понравилось, что нейросеть расположила все ключевые точки в логичном порядке и учла время на переезды и прогулки. Но есть нюансы:

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

Несмотря на тонкости, должна признаться, что для моей первой поездки маршрут оказался идеальным: я посмотрела исторические места, побывала на природе и очень вкусно пообедала!

– Ксения

Находка 2: Кухня на автопилоте

О чем вы говорите с нейросетью? Если не брать в расчет рабочие вопросы, то больше всего у меня чатов про... еду.

Я пользуюсь ChatGPT Plus и субъективно люблю его больше DeepSeek.

С чем мне помогает ИИ:

• Поиск и модификация рецептов
У меня аллергия на орехи и манго, я не люблю лук, сильно острое — и далее по списку. При этом я часто готовлю, но также часто задаюсь вопросом: «Что приготовить на завтрак/обед/ужин?»

Примеры моих запросов к нейросети:

• Input: ингредиенты, output: рецепт

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

Совет: чем конкретнее ваш запрос (например, «азиатская кухня», «без выпечки», «быстро»), тем точнее и индивидуальнее будет ответ ChatGPT.

С помощью нейросети я готовила не сосчитать сколько раз: разные виды ризотто, суп томатный, вегетарианский, брускетты и кесадильи на завтрак, пасты и куриное филе, которое до советов ИИ всегда получалось сухим.

Находка 3: «Птичий Shazam»

Знаете ли вы, какие птички поют весной в вашем дворе, в парке или на даче? Я не подозревала, пока мне не показали приложение для распознавания птиц по пению — BirdNET. Благодаря ему я узнала, что у нас на даче поют зарянки и пеночки-теньковки, а в кленах под окном перекликаются лазоревки.

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

Теперь это мое хобби: я уже собрала 59 наблюдений и открыла для себя 30 видов птиц!

Находка 4: Распознавание растений по фото

Любопытство у меня в крови: после птиц я принялась изучать растения на летних верандах. В этом случае мне на помощь пришло приложение для распознавания растений PlantNet: я делаю фото или выбираю из галереи — и вуаля, результат готов!

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

– Мария

Более популярный аналог — «Умная камера», встроенная в Яндекс.Браузер.

Так я с удивлением обнаружила, что невероятной красоты дерево, увиденное мной весной в Калининграде, — это сакура! Даже не пришлось ехать в Японию, чтобы попасть на ее цветение.

– Ксения

Обязательно попробуйте хотя бы одну из находок в предстоящие выходные, чтобы разнообразить свой досуг!

Это было сложно, но, превозмогая, я справился: с микроменеджментом, переделыванием задач за других и с «необходимыми» переработками.

Да, я «справился», но в реальности это был полный провал — я укоренил в себе смертельно опасные для лида паттерны. И когда я получил более крупный проект, новую команду, то моментально утонул в хаосе.

Проблема была в «поломке прошивки». Мозг инженера оптимизирован для решения задач, в то время как мозг лида должен быть оптимизирован для создания систем, которые решают задачи.

Сегодня я расскажу о пяти навыках, которые избавят вас от ненужных страданий и помогут уверенно вести команду вперед.

Навык 1: Делегирование, или как перестать быть «героем-одиночкой»

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

Ваш внутренний individual contributor захочет делать задачи сам, ведь именно это вы умеете делать лучше всего. При этом вы скорее всего не умеете грамотно делегировать.

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

Мой мозг инженера кричал: «Сделаю сам, ведь так быстрее». И я делал. Я забирал сложные задачи, засиживался, становился героем-спасителем. Результат достигнут, а остальное не имеет значения, верно? Я встревал и перепроверял, занимался микроменеджментом.

Но потом с ужасом осознал: из-за такого подхода члены команды не преодолевают трудности. Я своими же руками отнимаю у них возможности для роста.

Ваша ценность больше не в том, сколько кода вы напишете и сколько задачек закроете своими руками. Она в том, сколько пользы вы принесете совместными усилиями.

Полечить эту боль мне помогли два простых совета от моего руководителя:

Этот разговор перевернул мое восприятие проблемы. Я никогда не мог подумать, что загвоздка именно в доверии, но в итоге для меня это сработало.

Экспресс-терапия по делегированию:

1. Примите как факт: теперь вы — это ваша команда. Ваши общие успехи — это ваш успех. Замыкать всё на себе и быть «супергероем» — худшее, что вы можете сделать для себя, команды и организации.
2. Прямо сейчас распланируйте встречи one-to-one с членами своей команды, если вы этого еще не сделали. Проведите серию персональных встреч, посвященных навыкам и развитию. Вполне возможно, что кто-то хочет прокачать скиллы, которых не хватает вашей команде.
3. Попросите помощи у команды. Если вы растите людей правильно, они всегда будут готовы вам помочь и заодно подтянуть свои навыки.
4. Начните делегировать не самые критичные задачи, давайте людям право ошибаться и делать что-то неидеально. Направляйте, но ни в коем случае не перекидывайте задачи на себя на половине пути. Хвалите за выполненную работу и аккуратно вносите корректирующую обратную связь.
5. Постепенно делегируйте более важные и ответственные задачи. Не бойтесь: без работы не останетесь, а ваши люди со временем начнут справляться, поверьте.

Бонусные материалы:

• Используйте «ромб управления»
• 5 действий, чтобы команда полюбила one-to-one

Навык 2: Планирование, или как сделать работу команды предсказуемой

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

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

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

Как пофиксить проблемы с планированием:

1. Если вы, как и я, постоянно не укладываетесь в сроки, живете с ощущением, что задачи «сырые» и каждый спринт в них возникают новые подробности, которые меняют вообще всё, то вам точно не хватает грумингов бэклога. Займитесь командным календарем и поставьте туда ~4 часа таких встреч, распределенных по спринту. Организуйте их в то время, когда у команды еще есть энергия и вы готовы уделить внимание разбору задач.
2. Начните оценивать задачи не для галочки — используйте эти оценки. Объясните команде, почему это важно. Story points, человеко-часы, попугаи, футболки — не суть. Нам нужно понять, сколько и какой работы мы можем выполнять как команда за промежуток времени. Если знаем, сколько задач делаем за спринт, то можем прикинуть, сколько успеем за квартал.
3. Включите команду в процесс. Вы не начальник, вы — лидер команды. Выдумать задачи и раскидать их на людей — это не планирование, а путь в никуда. Дайте команде власть: позвольте им задавать вопросы, делиться своим мнением, не соглашаться с вами. Если на груминге и планировании говорите только вы — вы явно делаете что-то не так.
4. Планируйте от достижения цели, а не от списка задач. Задавайте вопрос не в духе «Что будем делать в следующем спринте?», а «Какого результата мы должны достичь к концу спринта?».
5. Оставляйте «буферы» для неопределенности. Не планируйте на 100% от доступной емкости команды. Это одна из ошибок, которую все мы допускаем в начале пути. Всегда будут срочные баги, внезапные запросы, больничные и те самые «сырые» задачи.
6. Используйте инструменты для визуализации планирования, которыми сможет пользоваться вся команда, а не только вы. Наше планирование изменилось навсегда, когда мы нашли удобный для себя инструмент: плагин Easy Agile для Jira.

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

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

Навык 3: Расстановка приоритетов, или как делать то, что действительно важно

Как только вы станете лидом, количество информации и опций многократно увеличится. Вы больше не сможете сказать себе: «Это не моя вотчина». И это будет больно, потому что будет казаться, что вы должны контролировать и делать вообще всё.

Здесь есть две составляющие: ваши личные приоритеты и управление приоритетами команды.

Сначала я столкнулся с тем, что у команды слишком много активностей: висит Pull Request, задача-блокер, соседняя команда пришла с дефектом на тесте, а еще какая-то встреча в календаре… Чувствовалось, что команда находится в постоянном стрессе от неопределенности, а от этого тревожился я и думал: «Как же мне это починить?»

Решили мы это раз и навсегда, зафиксировав свои приоритеты в документации:

1. Инциденты на продакшене.
2. Инциденты на стейдже.
3. Установка готовых поставок на прод.
4. Код-ревью мердж-реквестов.
5. Всё остальное.

А для закрепления создали дашборд с соответствующими фильтрами. Работать очень просто: сверху вниз опустошаем «корзинки», и, пока там не пусто, ничем другим не занимаемся. Как только всё опустошили — возвращаемся к плановым задачам.

Кстати, именно это нам помогло лучше работать по TBD (Trunk Based Development). Конечно, внедрить за один день не получится, но вы можете отрабатывать ситуации, напоминать своей команде о приоритетах и следовать им сами.

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

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

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

Бонус: моя любимая книга «Цель. Процесс непрерывного совершенствования» Элияху Голдратта — must read, который научит вас видеть то, что приводит к результату, а не просто «работать работу» по накатанной.

Навык 4: Искусство говорить «нет», или как отклонять запросы, не сжигая мосты

Мне было психологически сложно отказывать. Я боялся показаться несговорчивым, поэтому всегда говорил «да». А потом шел и выбивался из сил, пытаясь уместить необъятное, и избыточно нагружал команду работой, которая не вела нас к цели.

В сущности этот навык — разумное следствие предыдущего пункта про приоритеты. Чтобы заниматься самым важным, нужно научиться говорить «нет». Очень много говорить «нет».

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

«Я совсем ничего не успеваю, у меня весь календарь во встречах».

Знакомо? Скорее всего, вы не говорите «нет» второстепенным активностям. Хорошая новость: именно вы можете этим управлять.

Оцените, правда ли вы нужны на этой встрече? Правда ли эта задача такая срочная? Правда ли этот баг настолько критичен? Стоит ли разбираться в баге, по которому нет никакой фактуры и ничего не указывает на вашу систему?

Сомневаетесь? Спросите у своего руководителя: «Стоит ли мне заниматься активностью X?» Со временем вы начнете всё лучше понимать, что важно, а что второстепенно, и сами сможете решать, что стоит усилий вашей команды.

Бонус: простые практики, которые делают каждый рабочий день проще.

Навык 5: Manage Up, или как выстраивать продуктивные отношения со своим руководителем

Думаю, это тот навык, о необходимости которого я бы никогда не подумал, будучи начинающим лидом.

Когда ты разработчик, твой руководитель — это твой товарищ по команде. Вы вместе преодолеваете трудности, встречаетесь на дейлике и всегда в одном контексте.

Когда ты лид, твой руководитель уже на ступеньку выше, и правила становятся другими.

Несколько советов, как теперь взаимодействовать с вашим руководителем:

1. Приходя с проблемой, продумайте варианты решения и прямо озвучьте, какая помощь нужна от руководителя. Это сильно ускорит решение проблемы: вы не перекладываете ответственность на плечи начальства, а просите совета или конкретной помощи.
2. Периодически синхронизируйте планы, узнавайте боли вашего руководителя. Конечно, на вас будут транслировать планы и задачи, но не бойтесь регулярно уточнять его стратегические цели и приоритеты. Понимая, какие задачи и «боли» у него на верхнем уровне, вы сможете адаптировать работу своей команды так, чтобы вносить максимальный вклад в общий результат, а не просто закрывать задачи из бэклога.
3. Не скрывайте плохие новости, сообщайте о рисках сразу. Это не признак слабости, а демонстрация ответственности: руководитель получает возможность помочь до того, как ситуация станет критической, и может управлять ожиданиями на своем уровне.
4. Уважайте его время (если уж на то пошло, уважайте время всех людей, с кем работаете). Если у вашего руководителя несколько команд и множество проблем, решением которых он занят, старайтесь всегда давать контекст; используйте асинхронные способы коммуникации, если нет необходимости в срочном ответе.
5. Не бойтесь эскалировать, но соберите фактуру: нужно научиться определять ситуации, в которых вы уже ничего не можете сделать на своем уровне, и не бояться сообщать об этом вашему руководителю как можно скорее. Поверьте, он больше всех хочет, чтобы у вашей команды всё получилось.

Выводы

Переход из individual contributor в лида всегда непростой. Вам придется столкнуться с совершенно новыми для себя проблемами, при этом ваша старая «прошивка» будет вам скорее мешать, чем помогать. Надеюсь, мои рекомендации помогут вам преодолеть этот путь чуть менее болезненно.

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

Happy leading!

Автор: Вадим Ваганов, техлид
Канал Вадима для прагматиков, которые хотят большего

Привет! Меня зовут Валентин Дементов, я занимаюсь системным и бизнес-анализом уже 10 лет. За это время я успел поработать в проектах в сферах госсектора, энергетики, строительства и медицины. Сейчас я развиваю инвестиционные банковские продукты в Газпромбанк.Тех.

В этой статье наш практический кейс. Расскажу, как в командах стрима «Инвестиции» мы пытались решить проблему «требования vs разработка» и что у нас получилось: как объясняли инженерам, что хочет бизнес, чтобы они действительно поняли, что от них нужно. А еще как сделать планирование прозрачным и понятным для всех, чтобы каждый находился в контексте задач.

Один из новых подходов, которые мы попробовали в команде, называется «Три карандаша». Этот метод был разработан коллегами из департамента Agile-трансформации и активно применяется во многих командах Розницы. Используя его, команда визуализирует будущее решение при обсуждении постановок и требований к разработке банковских систем.

Рисовать идеи — обычная практика. Многие начинают с набросков на бумаге, но некоторые пропускают этот шаг и сразу приступают к написанию кода. Когда команды разработки перешли на удаленную работу, исчезли и обычные обсуждения у доски.

Есть разные методы, где используются рисунки: CJM, USM [+UI], event storming, C4 и другие. Каждый прием решает конкретные задачи: показать общую картину развития продукта, описать хорошие пользовательские истории, помочь на этапе бизнес-анализа и планирования.

По методу «Три карандаша» мы рисуем клиентский путь на пользовательских интерфейсах, а поверх него добавляем бэковую часть и внешние зависимости. Дальше я расскажу вам и про сам метод, про то, как мы адаптировали его в своей команде, и приведу реальные отзывы коллег об этой практике. Покажу примеры схем, прототипов и других визуальных методов, которые мы использовали, чтобы разработчики и тестировщики лучше понимали требования от аналитиков, а аналитики четко формулировали задачи.

Почему такая коммуникация стала важна для нас

Выделили основные сложности:

1. Текущие шаблоны требований к разработке это в основном текст, хотя графика для команды при обсуждении удобнее и понятнее.
2. Текст, каким бы подробным и структурированным он ни был, — это не гарантия понимания. Люди могут интерпретировать его по-разному, а иллюзия консенсуса опасна.
3. Объем работы часто кажется меньше, чем есть на самом деле, особенно когда все представляют задачу по-своему.
4. И главное: если потенциальные риски не выявлены в начале, их устранение позже потребует больше ресурсов.

Как сделать обсуждение понятнее? Мы решили начать рисовать. Картинки помогают выявить расхождения в восприятии. Если что-то кажется непонятным — нарисуй! Это может быть сложная часть пользовательского сценария или список условий для тестирования. Рисовать может любой член команды, не только аналитики. Даже если это займет время, оно окупится: в процессе часто возникают новые идеи или вопросы.

- дизайнер

Начали с анализа требований — бизнесовых и технических. Часто в таких случаях один специалист берет на себя обе роли: и бизнес-аналитика, и системного аналитика.

Обычно в бизнес-анализе используют схемы (например, BPMN), которые показывают последовательность действий или потоки данных. Раньше мы обходились без них, заменяя их короткими текстовыми требованиями, отфильтрованными согласующими департаментами.

Потом эти требования переходили к системному аналитику, который превращал их в форму технических заданий в Confluence и задачи в JIRA. Такой подход делал аналитика «бутылочным горлышком» — все зависели от его интерпретации.

«Хватит обмениваться документами. Начните обсуждать!»

После обучения методу «Три карандаша» мы изменили формат обсуждения задач. Прежде это были часовые встречи, где участники смотрели на макеты и пытались примерно оценить сроки анализа, разработки и тестирования.

Проблемы такого подхода:

●       Неточные оценки, из-за которых срывались сроки

●       Требования, которые всплывали уже на тестировании, возвращали задачу в начало

●       Расхождения между тем, что описали аналитики, и тем, что сделали разработчики. Такая ситуация дополнительно снижала мотивацию тестировщиков

Первым изменением стало разделение встреч на две: для бизнеса и для технических вопросов.

Бизнес-обсуждение нужно, чтобы разбить крупные задачи (эпики) на мелкие (пользовательские истории) и спроектировать пользовательские интерфейсы. Такое обсуждение ведет бизнес-аналитик. Еще в обсуждении участвуют владелец продукта, системный аналитик, технический лидер и коллеги из смежных команд, если мы уже сейчас понимаем, что будем от них зависеть. Основной инструмент — карта пользовательских историй (USM), которая основана на карте клиентского пути (CJM).

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

Пример схемы небольшой задачи:

Затем наступает время инженерного груминга «Три карандаша»

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

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

«Три карандаша». Применяем цветовую маркировку:

●       Синим отмечаем готовые решения, которые можно переиспользовать без изменений.

●       Зеленым — мы знаем, как изменить решение и договорились об этом здесь и сейчас.

●       Красным — непонятные моменты, требующие дополнительного исследования

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

Еще одно изменение: техническое обсуждение начинается с готовой карты сценариев из бизнес-встречи. Для проведения встречи с командой разработки мы готовим шаблон для технического обсуждения.

Пример готовой схемы:

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

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

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

Результаты

Приведу обратную связь от коллег:

- техлид

- разработчик

- техлид

- бизнес-аналитик

- дизайнер

Трудности

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

Преимущества рисунков

●       Запоминаются лучше текста

●       Помогают заметить пропущенные детали

●       Упрощают сложные задачи

●       Двойная польза: пока рисуешь, находишь слабые места в постановке и требованиях, а из-за наглядности другие быстрее их понимают

Недостатки

Схемы нужно поддерживать в актуальном состоянии, и это ложится на того, кто их создал.

Инструменты для рисования

●       Бумага и ручка

●       Маркер и доска

●       Microsoft Visio

●       Draw.io

●       Excalidraw и другие

Выводы

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

Раннее включение команды разработки повлияло на то, что ни одна задача не вернулась с разработки или тестирования на уточнение аналитики. Все требования были достаточно полными и однозначными, а формулировки и термины были сразу оговорены и зафиксированы.

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

Пара слов от автора метода «Три карандаша»:

Метод инженерного груминга и декомпозиции “Три карандаша” изначально создавался, как простой, интуитивно понятный и адаптируемый командами инструмент. Не существует каких-то “правильных Трёх карандашей” (если только они не синий, зелёный и красный J ), но существует магия достижения общего понимания будущего решения, незаметного прорастания в команде кроссфункциональности разработчиков, роста точности планирования и своевременного согласования планов работ со смежниками и достижения с ними договорённостей по инженерным контрактам. Всё то, без чего разработка любого продукта в крупной организации практически невозможна.

Валентин прошел обучение по курсу Каскадный грумминг и декомпозиция и Инженерный груминг “Три карандаша”, который на регулярной основе проводят Департамент Agile трансформации и Центр экспертизы бизнес-анализа Розницы. Затем он самостоятельно внедрил практику в свою команду. Ожидаемо, что практика визуально адаптировалась под команду, начала своё самостоятельное развитие. Это видно невооруженным глазом и является явным признаком обдуманного применения метода. Главный результат – предсказуемость, общее понимание и всё что я описал ранее перешло в команде на принципиально более высокий уровень, и этот уровень будет только расти.

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

Департамент Agile трансформации Центр экспертизы бизнес-анализа Розницы активно внедряют методы каскадного груминга и декомпозиции в команды нашего банка. В процессе внедрения, проявляется много интересной специфики, связанной с особенностями продуктов и платформ. Например, сейчас активно исследуется применение метода в ETL и при строительстве хранилищ данных.

Но самое главное, что метод создавался инженером для инженеров: чтобы было просто, наглядно и экономило время. Опыт команды Валентина и других команд показывает, что так он и работает.

Рустем Файзуллин

Agile-коуч

Департамента инженерной экспертизы и инструментов разработки