Всем привет, я Катя, развиваю Gramax. Мы часто говорим, что документация должна жить в одном ритме с продуктом. В этом кейсе как раз видно, что за этой фразой стоит на практике.
Команда CRM-платформы «Модус» от ИТ-холдинга Т1 переводит руководства пользователя и администратора из Confluence в Docs as Code. Задача — связать документацию с релизами продукта, сократить ручную сборку и сделать так, чтобы аналитики могли писать в Markdown без боли.
Подробно об этом мы поговорили с Екатериной, владельцем продукта «Модус», и Еленой, ведущим аналитиком, которая драйвила переход на новый процесс. В статье раскроем: что не работало в старой схеме, как команда выбирала инструмент, как прошел пилот и какого эффекта удалось добиться.
Что представляет собой Модус
«Модус» от ИТ-холдинга Т1— платформа для автоматизации бизнес-процессов взаимодействия с клиентами. Платформу используют крупные заказчики, в том числе банки, и крупнейшая авиакомпания России. Есть регулярные релизы, релизные ветки, руководства пользователя и администратора, технические спецификации, внутренние регламенты, инструкции для команд и материалы для поддержки.
Зафиксируем вводные.
Что за продукты. В основе — CRM-система «Модус». И еще несколько крупных бизнес-модулей, построенных на базе платформы: Маркетинг, Лояльность, Взыскание, Аналитика, Продажи, CPO, Сервис, Контактный центр.
Какая документация. Пользовательская документация: руководства пользователя и администратора, которые отдают заказчикам и партнерам.
Кто пишет. Основные авторы пользовательской документации — аналитики. Они описывают сценарии, ограничения и поведение системы.
Как отгружается. Продукт поставляется отдельно, документация живет в Confluence отдельно. Чтобы передать ее заказчику, специалисты выгружают нужные материалы, собирают Word-файлы, проверяют актуальность и версию, а потом отправляют документацию отдельным комплектом.
Проблема: «а что было в 27 версии?»
У команды несколько версий платформы в эксплуатации. Один заказчик на одном релизе, другой на другом, кто-то на промежуточной версии. И когда прилетает вопрос по методу, модулю или сценарию, нельзя ответить по последней странице в базе знаний. Нужно понять: в какой версии живет клиент и что именно было в этой версии.
Елена описала это очень точно:
«Отсутствие версионирования для нас было трэшем. Релизы выходят часто: каждый квартал, иногда каждый месяц. Один банк забрал 27-й релиз, другой — 28-й, третий — 31-й. А потом начинается: что было в таком-то методе? Как это должно работать в этой версии?»
Елена, ведущий аналитик
Вот здесь и начиналась настоящая аналитическая разминка: найти не просто актуальную страницу, а правильный срез под конкретный релиз.
«Если нужно было отдать документацию по какой-то промежуточной версии, это становилось задачей с тремя звездочками».
Елена, ведущий аналитик
В старом процессе продукт и документация ехали разными маршрутами. Продукт поставлялся сам по себе, а документацию потом нужно было собрать: выгрузить, привести в нужный вид, отправить, проверить, что не уехало лишнее и не потерялось нужное. Где-то страницы «на будущее», где-то старые материалы, где-то фрагменты только для внутреннего контура. На практике многое держалось на людях, которые помнили, где что лежит и как из этого собрать комплект.
«Где-то красным помечено: этого еще нет, не дай бог кто-то это выгрузит. А что было в 27-й или 28-й версии — уже не разберешь».
Елена, ведущий аналитик
Команде нужно было не просто «перейти из Confluence». Нужно было сделать так, чтобы:
Документация версионировалась вместе с продуктом
Под каждый релиз можно было получить правильный срез
Пользовательские материалы поставлялись вместе с продуктом
Команды писали в едином формате и по единым шаблонам
Аналитикам не пришлось становиться разработчиками
Разработчики могли продолжать работать привычными инструментами
Так Docs as Code перестал быть модной концепцией из докладов и стал вполне практичным ответом на вопрос: «как сделать так, чтобы документация жила тем же ритмом, что и продукт».
Как подбирали инструмент
На уровне концепции про Docs as Code: документация хранится в Git, пишется в Markdown, проходит ревью, живет в ветках и релизах. Разработчик в этот момент обычно кивает: знакомо, понятно, поехали.
Аналитик в этот же момент может внутренне напрячься. Потому что между «пишем в Markdown» и «подготовить нормальное руководство пользователя» внезапно появляются папки, пути к картинкам, синтаксис таблиц, индексы и еще несколько слов, которые вообще-то не про смысл документации.
Сначала пошли смотреть, как похожая история уже устроена у разработчиков. И быстро стало ясно: если просто принести аналитикам сценарий разработчиков, сопротивление будет вполне рациональным.
«Уже на этапе изучения я поняла, что плыву: нужно положить файлы в какие-то папки, потом на них сослаться, чтобы указать картинку в тексте. Тут решетки, тут точки, тут палочки. Чтобы таблицу нарисовать — столько приседаний. Я была в шоке: сколько времени я буду на это тратить?».
Елена, ведущий аналитик
Нужен был инструмент, в который можно привести много аналитиков и не потерять их между ветками и коммитами. Gramax попал в список не как заранее выбранный фаворит, а как один из вариантов после рекомендаций технических писателей. Его просто попробовали рядом с другими инструментами.
После нескольких болезненных попыток собрать даже небольшую структуру в более технических инструментах реакция была следующей:
«В одном из инструментов я, наверное, полдня потратила на то, чтобы создать структуру из трех страниц. Это было совсем не очевидно. Потом дошла очередь до Gramax, и реакция была: ничего себе, как удобно».
Елена, ведущий аналитик
Это было как рабочее облегчение: наконец-то понятно, где страницы, где структура, как вставить картинку и куда нажимать дальше.
В этой истории Gramax сработал как редактор для авторов: место, где аналитик может спокойно писать, видеть структуру, работать со страницами, таблицами и изображениями без ощущения, что он сейчас программирует текст. При этом под капотом остаются Markdown и Git, то есть команда не запирается в закрытом формате. Елена назвала это «не прибито гвоздями»:
«Кто-то пользуется Obsidian, кто-то привык к VS Code, и все это не противоречит друг другу. Все хранится в Markdown, открывается в разных инструментах, и мы не заставляем всех обязательно пользоваться только Gramax».
Елена, ведущий аналитик
Хорошая формулировка, потому что в ней ровно та гибкость, которая нужна смешанной команде. Gramax помогает тем, кому нужен визуальный слой, но не ломает привычки тех, кто нормально живет в VS Code. Процесс общий, источник общий, формат общий, а входов несколько.
Как проводили пилот. Семь команд и подозрительно мало вопросов
Пилот начали с платформы — основной части «Модус». Перед запуском команда подготовила инструкции первого входа: как подключиться, получить доступ, сделать базовые операции, не споткнуться о GitLab. Отдельно описали слияния и ревью.
А дальше случилась лучшая метрика для такого внедрения: вопросов было мало. Елена сказала, что успешность пилота стала понятна именно по единичным обращениям от других команд:
«Почему мы решили, что пилот успешен? Потому что другие команды обращались с вопросами лишь единично. Ситуаций в духе "не знаю, не понимаю" было действительно очень мало».
Елена, ведущий аналитик
Речь о нескольких десятках людей в платформенной команде и еще нескольких десятках в продуктовых командах. Плюс постепенно подтянулись не только аналитики: разработчики и архитекторы тоже начали переносить инструкции, регламенты и технические материалы. Потому что если все рядом с продуктом и нормально версионируется, держать знания в разных углах становится просто неудобно.
«Мы не можем сказать, что раньше все было совсем разрозненно. Процесс уже был достаточно зрелым, и все в целом знали, где что лежит».
Екатерина, владелец продукта
Новый подход не создал знания с нуля, а добавил к ним версионность и связь с продуктом:
«Сейчас это еще больше систематизируется и укладывается в версионируемую историю, привязанную к конкретной версии продукта».
Екатерина, владелец продукта
Это важная разница. База знаний отвечает на вопрос: «где лежит информация»? Docs as Code добавляет второй вопрос: «к какой версии продукта она относится»?
Как переносили все из Confluence
У команды пространство в Confluence было большим и общим. Поэтому пришлось разбирать: что идет в пользовательскую поставку, что остается внутренним, что устарело, что надо переписать, а что можно забрать почти как есть.
Да, часть работы была ручной. На вопрос новых команд «а как переносить?» ответ местами был: «Ctrl-C, Ctrl-V». Не мечта автоматизатора, зато отличный повод наконец посмотреть на материалы глазами читателя.
Например, команды договорились о едином шаблоне руководства пользователя. Раньше каждый мог вести раздел как привык, а потом кто-то на этапе сборки приводил все к общему виду. В новом процессе так уже не очень получается: если материал едет в поставку и версионируется вместе с продуктом, качество структуры должно быть на стороне авторов.
Материалы начали причесывать:
Пересобирать слишком большие таблицы
Убирать лишнее
Актуализировать скриншоты
Выравнивать структуру руководств
Отделять пользовательское от внутреннего
В этом и был полезный побочный эффект миграции. Пока документацию можно было собрать «как-нибудь потом», часть ответственности оставалась на людях, которые выгружали и приводили ее к общему виду. Когда документация стала частью поставки, «потом поправим» стало хуже работать.
Как работает сейчас
Если разложить текущую схему по слоям, получается понятная конструкция.
Первый слой — авторский
Команды пишут и редактируют материалы в Gramax или в привычных Markdown-инструментах. Аналитикам Gramax дает нормальный визуальный вход, разработчикам не мешает работать как с обычным репозиторием.
Второй слой — хранение и процесс
Документация лежит в GitLab. Есть ветки, merge request, ревью, релизные ветки. Отдельный процесс изобретать не стали: взяли механику, которая уже работает в разработке, и приложили ее к документации.
Третий слой — поставка и отображение
Пользовательская документация собирается в портал и едет вместе с продуктом. В первую очередь перевели руководства пользователя и администратора: то, что действительно нужно заказчикам и партнерам для работы с системой. Следом подтягивается техническая документация: спецификации, хендбуки, регламенты, материалы разработчиков.
«Мы разворачиваем поставку: продукт поднимается на серверах, и сразу же вместе с ним есть документация. Развернули портал, развернули сервисы — все на месте. Не нужно ждать, пока кто-то пришлет по почте Word-файлы или что-то подобное».
Елена, ведущий аналитик
Если поддержка нашла пробел, команда может дописать материал, донести исправление, и обновленная документация окажется доступна тем, кому нужна:
«Если появился пробел — мы его описали, донесли фиксом. И обновленная документация доступна всем пользователям одновременно. Мы просто внесли фикс в версию, и нам не нужно рассылать документацию отдельно».
Елена, ведущий аналитик
Не надо искать последнюю версию Word-файла, уточнять у соседней команды, что именно отправили клиенту, и надеяться, что все совпало. Версия продукта и версия документации наконец начинают смотреть в одну сторону.
Что изменилось на практике
Версионирование
Теперь документацию можно связать с конкретной веткой продукта и конкретным релизом. Для команды с несколькими релизами в эксплуатации это не просто приятная опция, а база: иначе быстро становится непонятно, какая инструкция к какой реальности относится.
Меньше ручной сборки
Раньше были люди, которые собирали документацию из Confluence, приводили ее в нужный вид и передавали дальше. Сбор всего комплекта занимал примерно 40 часов. Сейчас по документации платформы время на передачу сократилось примерно в 2 раза, но часть ручной работы остается из-за клиентов, которым нужен DOCX. Когда все модули переедут в Docs as Code, команда ожидает сокращение примерно до 4 часов на весь процесс.
Документация ближе к пользователю
Человеку проще найти ответ на свою задачу.
«Когда документация не лежит в тысячестраничном Word, где нужно что-то найти и прочитать, где может поехать верстка, а ссылки иногда ведут на внутренние ресурсы, с ней проще работать. Если инструмент дает быстрый ответ именно на твою задачу и убирает лишний шум, вероятность, что документацию действительно прочитают, сильно возрастает».
Екатерина, владелец продукта
Поддержке проще искать ответы
По словам Екатерины, портал теперь в первую очередь используется как актуальный источник:
«Сейчас поддержка в первую очередь идет в портал, потому что он самый актуальный. [...] Им стало гораздо проще: гораздо меньше времени уходит на то, чтобы найти ответ».
Екатерина, владелец продукта
Знания начали подтягиваться к продуктовой цепочке
Разработчики, архитекторы и аналитики видят, что инструкции, спецификации и регламенты можно вести рядом с продуктом, в понятной версионной модели.
«Не только аналитики, но и разработчики, архитекторы, которые пишут свои инструкции и статьи, постепенно переезжают, потому что так удобно вести материалы. [...] Все получается в единой цепочке, в общем контексте, неразрывно от основного продукта».
Екатерина, владелец продукта
Сложности: порог входа, миграция и переходный период
Первая сложность — стартовый страх перед Docs as Code. Для аналитиков Git, ветки, Markdown выглядят как территория разработчиков. Поэтому команде пришлось отдельно продумать первые шаги, инструкции и поддержку новичков. Низкий порог входа Gramax здесь оказался условием, чтобы люди вообще начали.
Вторая — сама миграция из Confluence. Автоматического волшебства не случилось. Содержательный перенос все равно делается руками: не просто копировать текст, а пересматривать структуру, чистить материалы и приводить их к шаблонам.
Третья — переходный период. Платформа уже перешла на новый подход, а бизнес-модули подключаются постепенно. Значит, какое-то время существуют две реальности: часть документации уже в новом процессе, часть еще в старом. Это довольно обычная цена поэтапного перехода.
Четвертая — методологическая. Когда документация становится частью поставки, к ней растут требования. Нужно договориться, что должно быть готово к релизу, кто ревьюит материалы, как выглядят шаблоны, где проходит граница между пользовательской и внутренней документацией. Неприятно только на старте, зато потом меньше сюрпризов перед релизом.
Бонусом: Markdown оказался удобной базой для ИИ
В разговоре Екатерина и Елена отметили еще один момент. Когда документация переезжает в Markdown и Git, она становится не только удобнее для версионирования. Она становится нормальным структурированным корпусом знаний.
А с таким корпусом уже проще думать про поиск, агентов и сценарии, где система помогает находить ответы не только по документации, но и по коду:
«Markdown — прекрасно структурированный формат, а значит, дальше можно думать про агентов и поиск: "найди мне, как это сделать" — и мы запускаем его прямо в Git. Вот тебе и документация, и код».
Елена, ведущий аналитик
То есть ИИ здесь появляется как следующий слой над знанием, которое уже нормально разложили.
И это важная мысль. ИИ плохо помогает там, где знания лежат вперемешку, без версий, структуры и понятной ответственности. А вот когда документация приведена к единому формату, связана с релизами и живет рядом с продуктом, эксперименты становятся гораздо менее шаткими.
Что дальше
Сейчас команда масштабирует подход дальше. Платформа уже прошла основной путь, следом переходят бизнес-модули. В планах — развивать поставку документации, переносить больше технических материалов, улучшать внутренние и внешние порталы и использовать единый Markdown-источник для разных сценариев публикации.
Отдельная тема — публичная документация. Сейчас часть материалов доступна в более традиционных форматах, но команда смотрит в сторону портала со структурой и поиском.
«Да, это у нас в планах, просто пока до этого не добрались. [...] Ждем, когда наши продукты тоже переведут свою документацию в портал. Тогда можно будет технически продумать, как все разместить и сделать удобно».
Екатерина, владелец продукта
Логика та же: если источник один, его можно по-разному собирать, показывать и отдавать разным аудиториям.
Мне нравится в этой истории, что команда не просто внедрила инструмент. Инструмент важен, но задача была шире. Команда увидела, что документация уже не успевает за продуктовой поставкой, и не стала лечить это еще одним регламентом.
Они взяли процесс, который уже работает в разработке, адаптировали его для аналитиков, снизили порог входа, договорились о структуре и перенесли документацию ближе к продукту. В итоге пользователь получает не просто релиз, а релиз с актуальным знанием внутри.
Gramax здесь оказался мостом между Confluence и Git, между аналитиком и Markdown. Пожалуй, это хороший итог.
