Гайд для команды технических писателей: как передать создание документации AI-агентам

Рассказываем на опыте команды Битрикс24, как создать AI-конвейер для документации, как оценивать его эффективность и чему теперь учить технических писателей.

Как устроен конвейер

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

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

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

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

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

Как настроить процесс AI-генерации контента

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

Мы проходили этот путь поэтапно. Сначала снизили зависимость от разработчиков, научив технических писателей самостоятельно вызывать новые методы API в тестовой среде и смотреть, что они возвращают на самом деле, затем постепенно стали передавать эту задачу AI и параллельно учились писать скиллы, а затем объединять их в последовательную цепочку действий.

Учим технических писателей работать без помощи разработчиков

Во многих командах процесс создания документации выглядит так:

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

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

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

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

Это сильно упрощает жизнь команде, и разобравшись как следует в новом процессе, вы начнете постепенно делегировать эти задачи AI-агентам.

Последовательно подключаем AI-агентов

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

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

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

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

Как правильно работать со скиллами для AI-конвейера документации

Хранение

Хранить скиллы удобнее в общем внутреннем git-репозитории, едином для всей команды. Если вы создаете документацию для нескольких продуктов, заведите для каждого свою папку: в ней лежат скиллы — каждый в отдельной папке со своим инструктивным файлом — и общие правила продукта.

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

Написание

Скилл — это не просто текстовая инструкция, а файл с коротким именем и точным описанием: когда именно агент должен его подключить, а когда — нет. Например, «используй для таких-то запросов», «не используй, если речь только о примере кода — для этого отдельный скилл». Дальше в файле следует пошаговая инструкция, что агент должен делать на этом шаге. У части скиллов в папке лежат вспомогательные файлы, на которые ссылается основная инструкция, например, отдельный файл с правилами перевода или чек-лист критериев для конкретного типа страницы.

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

Использование

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

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

Как оценивать эффективность перехода на AI-генерацию

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

Для нас количественный показатель принципиально важен, так мы видим, насколько быстрее и больше мы стали выдавать контента. Показательнее всего сравнение год к году. Например, в августе 2025 г. мы создавали в среднем 20,7 единицы контента на человека, в августе 2026-го — 113,6. За год производительность выросла в 5,5 раза.

Но у количества есть обратная сторона — с помощью AI можно быстро нагенерировать очень много плохого контента. Поэтому как только вы увидите, что скорость выросла, подумайте над тем, как измерять не только объем, но и качество. Самый рабочий вариант — разработать критерии качества для каждой страницы и оценивать их, например, от 1 до 10. В оценку могут войти такие критерии, как обнаруживаемость методов, полнота описания параметров и структуры ответа, примеры кода, коды ошибок и др. Для разных типов материалов они могут отличаться.

У нас есть собственная метрика AI Friendly Index (AFI). Это оценка по 100-балльной шкале, которая формируется из 10 критериев. Она показывает, хватает ли странице информации, чтобы по ней можно было написать рабочий код, не заглядывая в исходники. AI-агент сам оценивает подготовленный текст по этой метрике и если баллов не хватает, он не просто ставит низкую оценку, а показывает список конкретных проблем и что именно нужно поправить.

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

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

Как поменялась профессия технического писателя и к чему теперь их готовить

С появлением в отделе AI-инструментов задачи технического писателя полностью поменялись. Теперь он не пишет и не редактирует ответы разработчика. Он выстраивает процесс работы AI-агентов: создает скиллы и проверяет результат.

Мы полностью перешли на AI-генерацию. Раньше каждый сотрудник в отделе назывался технический писатель, сейчас это AI-контент-инженеры. Да и сама наша команда документации неофициально переименовалась в команду AI-контента.

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

Первый навык — вычитка и фактчекинг чужого, сгенерированного текста. Это совсем не то же самое, что вычитка своего: AI-черновик читаешь более подозрительно, специально ищешь, где агент мог додумать за автора. У этого навыка свой предел выносливости, теперь сотрудники устают по-другому и быстрее, чем от самостоятельного написания текста. Когда вы начнете писать документацию с помощью AI, вам придется выработать новый рефлекс — перестать читать текст как читатель и начать читать его как проверяющий. На формирование новой привычки уйдет несколько недель.

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

Рекомендации

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

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

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