Битословие

Как агенты встраиваются в человеческие процессы документирования Чтобы ответить на это вопрос, сначала нужно понять жизненный цикл задачи на документацию. Возможны разные варианты, но примерный процесс может выглядеть так: 1. Узнать об изменении функциональности. 2. Погрузиться в контекст, изучить исходники, поговорить с экспертами. 3. Понять, где и как описать это изменение и в каком объеме. 4. Подготовить черновик и сразу создать пул-реквест. 5. Согласовать изменения с ответственными, пройти ревью. 6. Применить правки, убедиться, что все проверки пройдены. 7. Опубликовать изменения. В предыдущие годы, когда мы использовали нейросети для своих задач, наибольший эффекты нейронки оказывали в момент понимания контекста (например при анализе кода) и подготовки черновых вариантов текста. Агенты дают возможность ускориться значительно сильнее. Прежде всего, агенты могут можно подключить на самой первой стадии, так как они прекрасно работают с историей Git с помощью обычных инструментов командной строки. Сложно переоценить возможность в конце месяца запустить анализ коммитов в рамках подготовки релизнот и узнать, что пару недель назад кто-то втихую добавил пару параметров в редко используемый метод и забыл об этом рассказать. После получения человеком сигнала об изменениях из любого источника, агент по команде может сам добавить описания изменений в нужное место, если он понимает структуру документационного проекта и у него есть шаблоны, инструкции и примеры для такого действия. После этого нужно будет только посмотреть результат самостоятельно и/или позвать кого-то на ревью, то есть стадии с 2 по 5 проходятся за пару минут. Экономия времени будет возрастать вместе с количеством параметров и других сущностей, которые обрабатываются в рамках одной задачи.

Что нового в Битословии за вторую половину 2025 года Я традиционно не подвожу личные итоги, зато пишу чейнжлоги: 1. Написал 5 новых статей для своего сайта. Четыре из них — про навыки, одна — обзор стандартов локализации чисел, дат и валют. 2. Разобрал и показал на примере способы эффективного использования Qwen в качестве личного ассистента (первая часть, вторая часть). 3. Написал про иерархию Данные-Информация-Знания-Мудрость. 4. Начал выкладывать посты с контекстом для своего будущего доклада про агентов в документации, что потихоньку превращается в изложение моего видения вайбдокинга. Первый пост из этого цикла. Мне также было интересно свериться с моим видением того, как ИИ потенциально угрожают профессии технического писателя (первый июльский пост с прогнозами, когда я только подступался к реальному внедрению агентов). 5. Опубликовал всего один пост в рубрике #чтиво, про принципы проектного менеджмента в NASA. Всех читателей с наступающим, увидимся в следующем году!

Протестировал Zensical от создателей Material for MkDocs Статья: https://alexjameson.github.io/articles/zensical-review/ Созданная документация: https://alexjameson.sourcecraft.site/pink-sync-docs/ Не так давно команда разработчиков Material for MkDocs объявила, что они больше не будут заниматься развитием проекта, представив ему на замену Zensical. Я не мог удержаться от того, чтобы проверить новый SSG в деле. Новый генератор уже получил переписанное ядро, сборщик и поиск, а в части публичных фич пока что предлагает совместимость со всей экосистемой плагинов и расширений MkDocs. В дальнейшем команда добавить больше оригинальных фич, например MDX-подобные компоненты и генерацию API из коробки. Может показаться, что это пост не про нейронки, но им тоже нашлось применение. Документацию для примера я подготовил за два дня с помощью Claude Sonnet 4.5, бюджет — около 1 миллиона токенов плюс сколько-то токенов моего мозга на проектирование, ревью и доработку результатов. Сначала я создал спецификацию OpenAPI для абстрактного сервиса для синхронизации баз данных, затем проработал внешний вид и необходимую функциональность сайта в ТЗ, а потом на основе ТЗ и спецификации создал документацию в Markdown. Также в качестве эксперимента я задеплоил получившийся статический сайт на SourceCraft Sites, наш аналог GitHub Pages.

Уровни автономности нейросетевых инструментов Продолжаю прогрев к докладу на TECHWRITER DAYS 3 в марте. В этом посте речь идет об инструментах, которые используются для документации, но в целом те же уровни можно применить и к большинству других доменов. Каждая следующая стадия из перечисленных ниже может включать инструменты и техники из всех предыдущих. 1. Ассистент Очень умный поисковик, позволяет разобраться в новых темах и подготовить черновик. Работает в отдельном интерфейсе вроде чат-бота, нужно переносить результаты работы вручную. 2. Валидатор Проверка текста или файлов на ошибки и соответствие правилам. На этой стадии мы были в прошлом году, когда рассказывали про линтер в докладе. Может запускаться как часть CI/CD или с помощью плагинов в редакторе кода, IDE, Word или аналогах и поставлять результаты в том же интерфейсе, в котором проводится работа с текстом. 3. Полуавтономный агент Выполнение отдельных задач тем же способом, которым из выполняет человек: четко прописанное задание, предоставленный контекст в виде списка целевых файлов, шаблонов и примеров, запуск по команде. Контекст сохраняется между запусками только при необходимости, если задача слишком объемная для выполнения за одну итерацию. Опционально использование сабагентов, но в основном один агент пытается выполнить задачу за одну итерацию. Изменения после работы агента в исходники после ревью и одобрения человеком. Типичные инструменты — от плагинов и форков VS Code до новых инструментов вроде Claude Code. Здесь мы с командой сейчас. Мой любимый юзкейс — генерация релизнот. 4. Автономные агенты К этому я подступаюсь в рамках экспериментов: Автоматические пайплайны, которые могут запускаться по триггерам без участия человека. Выполнение не только отдельных задач, а автоматизация целых процессов. Множество агентов могут работать параллельно над разными задачами. Контекст сохраняется между запусками агентов, например в memory banks с проработанными стратегиями обновления. Ревь

Дружеский прогрев Большинство флагманских моделей сейчас мультимодальны, то есть они понимают как текст, так и графику и звук. В контексте документации это наводит на вполне очевидную мысль: если нам нужно описать интерфейс, то почему бы не воспользоваться такими возможностями моделей для быстрого создания инструкций? Я поэкспериментировал с этим подходом и оказалось, что есть плюсы и минусы. Мне очень понравилось кидать в модель скриншот с минимальным пояснением и смотреть, как она обновляет фрагменты инструкций, когда я вижу, что какой-нибудь пункт в интерфейсе переехал. Но в реальности это задача, на которую я и так потратил бы не более получаса. Мне хотелось большего, и я подготовил комплекс из навыков агента, правил и шаблонов для создания полноценных инструкций на основе реального интерфейса или скриншотов из фигмы. Первая проблема, с которой я столкнулся, заключалась в том, что названия элементов в интерфейсе у нас в исходниках приводятся в виде переменных. Эти же переменные используются и в самом интерфейсе, что позволяет нам чаще всего иметь актуальные тексты из интерфейса в документации. Вторая проблема была глобальнее — изображения показывают статическое состояние интерфейса. Это неплохо в простых случаях, но чаще всего в интерфейсе есть интерактивные элементы, которые еще и могут быть вложенными. В этом случае самая важная часть инструкции как раз заключается в понятном человеку сценарии взаимодействия со всем этим богатством. В итоге я отказался от создания полноценной документации по скриншотам из-за нестабильности результата, а вот мой хороший знакомый Дима Развозжаев (@tekhpisovoe) — не отказался. Опытом успешного использования он поделится в своем докладе, приходите послушать его 28 марта на TECHWRITER DAYS 3!

Сейчас за рассказ об ИИ дают выступить, но скоро будут давать в морду Ну или вроде того. С 2023 года мы успели перерасти этап отправки непрошеных ответов LLM в чаты посреди человеческого общения и несколько сеансов массовой паники по поводу способности ИИ решать любые задачи за копейки — от управления базой знаний до задач SRE. Потихоньку перешагиваем даже детские болезни внедрения в компаниях, когда заказчики вместо реального ревью могут попросить агента протестировать результат, провалидировать документацию или просто дать обратную связь. Сейчас ИИ где-то начал или начинает приносить реальную пользу после первой волны хайпа, когда большинство проектов внедрения проваливалось, но при этом у ИИ остаётся всё меньше места в публичном пространстве. Никто не хочет слушать о том, как кто-то другой научился решать свои задачи с помощью нейросетей и насколько он стал продуктивнее. Я объясняю это и пресыщенностью, и тем, что сформировались две противоположные позиции. Например, в мире опенсорса Zig, Gentoo Linux, QEMU и Ghostty прямо запрещают использование ИИ для изменений от сторонних контрибьюторов. А такие проекты, как Linux Kernel, Django и Apache Software Foundation, сняли явные запреты либо полностью, либо частично, требуя обязательного раскрытия использования ИИ. Вместо этого они выдвинули требование наличия человека-контроллера (human-in-the-loop), несущего ответственность за результат. Если подумать о том, что вызывает такую реакцию на нейроконтент там, где давно обещают полное превосходство ИИ, я бы выделил отсутствие человеческого опыта, компетенций и просто видения за идеальным усреднённым продуктом. То же самое можно сказать и про тексты — вы ведь тоже бросаете статью, если в ней слишком много нейрояза? В какой-то момент я понял, что это раздражает настолько, что удалил из CI своего блога все ИИ-проверки, чтобы текст мог быть не идеален, но читался легче. Где-то тут, думаю, лежит и реальный предел возможностей агентов по работе с документацией: нельзя за

Продолжим размышление о том, где может лежать предел возможностей агентов при подготовке документации. В качестве основного метода анализа я использую соотношение типов создаваемой документации с иерархией Данные - Информация - Знания. Вне рамок этого поста я также использую Diataxis и Seven-action documentation model. TL;DR 1. Если документация предполагает нечто большее, чем справочник API для библиотеки или набор простых пошаговых инструкций для b2c-платформы, сильно возрастает значимость информационной архитектуры. 2. Построение ментальной модели, которая будет учитывать не только форму текста, но и его восприятие пользователями — задача куда более сложная, чем научить агентов создавать идеально грамотную документацию по шаблону. Я не уверен, что эта задача решаема с приемлемым уровнем качества на горизонте нескольких лет. 3. Если в треугольнике «Время - Качество - Стоимость» можно пожертвовать как качеством структуры, так и стилем текстов, или если шаблонные решения и есть целевое состояние документации, то можно положиться на агентов практически полностью. Итак, у нас есть данные, которые агенты умеют обрабатывать и передавать без каких-либо потерь. При этом понятно, что данные в смысле DIKW редко присутствуют в документации как таковые. Далее идет уровень информации, то есть данных с определенным контекстом. К этому уровню я отношу справочники и, с определенными оговорками, инструкции. Здесь также очень большие возможности для автоматизации. Проблемы начинаются на уровне знаний и выше. Чтобы понять суть этих проблем, я бы предложил посмотреть на то, как агенты пишут код. Код можно покрыть любыми тестами, от простых юнит- до E2E-тестов, провести статический анализ, прогнать через линтеры, скомпилировать и так далее. Таким образом можно гарантировать, что код решит поставленную задачу. Тексты и дополнительные материалы также можно сделать грамотными, можно высчитать метрики типа индекса Флеша-Кинкейда (осуждаю), снабдить необходимыми ссылками и метаданны

Пример документации, которую стоит читать самостоятельно Показал пост выше в одном сообществе и понял, что из текста непонятно, какую конкретно документацию я считаю предназначенной для людей. Проиллюстрирую примером из сегодняшней практики: Я захотел развернуть на своей виртуалке инстанс SilverBullet, простого клиент-серверного ПО для ведения базы знаний. Я составил план для агента, в котором ему нужно было прочитать документацию по ссылке, подготовить окружение и выбрать способ деплоя, при котором защита базы знаний будет обеспечиваться не только за счет аутентификации по паролю при условии доступа как минимум с трех устройств с разными ОС. Этого явно недостаточно, открытый порт, доступный из интернета — постоянная мишень для тысяч (или миллионов?) ботов, сканирующих и пытающих достучаться до любого открытого эндпойнта. Агент (Kimi k2.6+Kimi CLI) предложил несколько вариантов, причем больше всего ему нравилась идея использовать Tailscale с бесплатным аккаунтом для создания VPN в смысле настоящей виртуальной частной сети. Идея в общем-то неплохая, но в основе Tailscale лежит блокируемый у нас WireGuard, а ещё я в принципе не хочу завязываться на внешнюю систему для контроля доступа. Поэтому я отклонил все предложенные варианты и решил в стиле старой школы самостоятельно прочитать доку. Так как сам по себе SilverBullet — это ПО для управления базами знаний, его документация не содержит какой-то специфики для создания защищенного соединения, этим должен заниматься пользователь. Зато в документации нашлась секция со ссылками на посты от комьюнити, один из которых показывал, как настроить знакомый мне сервер Caddy и самостоятельно управлять сертификатами, чтобы только доверенные устройства могли установить TLS-соединение. Я мог бы избежать траты 20 минут на оценку вариантов, предложенных агентом, если бы потратил 5 минут на изучение соответствующей секции в документации, но это знание, как обычно, пришло потом. Для потребителей документации это может значить, что

Как выбрать модель для задач, связанных с документацией и управлением знаниями https://alexjameson.github.io/articles/choosing-llm-for-docs/ TL;DR Главная развилка — можно ли в вашей ситуации отправлять данные наружу. Модели у внешних поставщиков и дешевле, и мощнее того, что вы сможете развернуть у себя. Рассказы про полную автоматизацию всех процессов и замену людей — это рассказы про практически неограниченный доступ к фронтирным моделям последних поколений. Модели Anthropic и OpenAI опережают лучшие китайские модели минимум на поколение. Требования к мощности модели определяются самой сложной частью пайплайна. В большинстве случаев стоит выбрать самую мощную мультимодальную модель из доступных. Две основные категории задач: задачи по созданию контента и вспомогательные задачи, например ревью, поиск информации, расшифровка и суммаризация созвонов, мониторинг актуальности документации и так далее. Внутри категорий есть градация по степени неопределённости условий, в которых должна работать модель. Чем выше степень неопределенности и масштабнее задачи, тем сильнее растут требования к модели. Это краткое изложение основных мыслей, подробнее читайте на сайте.

Делюсь своим навыком для агентов из пет-проекта Исходники здесь: https://github.com/AlexJameson/agent-utils/tree/main/skills/print-image-prep Где-то с 2018 года я развиваю и поддерживаю сайт с онлайн-галереей Евы — https://evailves.ninja. С момента запуска он работал на WordPress, хотя успел несколько раз сменить хостера и регистратора, пока не осел на ВМ в Yandex Cloud. Для онлайн-галереи важно иметь изображения в хорошем качестве, но чтобы они при этом могли без проблем загружаться в полном формате на любом устройстве. Примерно схожие требования выдвигают кураторы при отборе и печатники при подготовке открыток. Я сформировал следующий универсальный набор характеристик: разрешение 300 DPI с сохранением исходного соотношения сторон (универсально, в отличие от PPI), цветовая схема в RGB, формат JPEG (в CMYK для печати можно перевести отдельно). Навык категоризирует изображения по степени соответствия требованиям, смотрит на метрики, апскейлит изображения одним из способов: либо по методу Ланцоша, либо с помощью одного особо хитрого бинарника для самых низкокачественных изображений. После установки библиотек все работает локально, можно запустить через CLI без графического интерфейса. В целом, после нескольких десятков запусков в Kimi CLI я вполне доволен, получается вполне крепкое среднее качество без возни с каждым отдельным изображением. Очевидно, что подход можно переиспользовать и для чего-то более практичного, например для скриншотов и иллюстраций, которые можно разместить в документации или в блоге.

Выйти из гонки моделей Чем дольше я работаю с агентами, тем больше меня раздражает политика ведущих вендоров в плане развития их моделей. Кажется, уже третье поколение, начиная с Opus 4.7, я думаю, что хочется зафиксировать качество и цену где-то на этом уровне и просто настроить конвейер для решения задач. Но вендорам нужно зарабатывать деньги и выводить в плюс свои финансы, поэтому появляются новые модели, меняются токенизаторы, выводятся из эксплуатации части мощностей для старых моделей и все в таком духе. Я точно помню, что нормально генерировать релиз-ноты я научился с Claude Sonnet 4.6, но сейчас он путается даже на стадии анализа истории Git за месяц, не говоря уже о качественной суммаризации и следовании разветвленной системе правил. Хочется строить процессы, предсказуемые как в техническом, так и в экономическом плане, чтобы было точное понимание, что и за сколько мы сможем делать через полгода при масштабировании на произвольное количество человек. Хочется не зависеть от меняющихся условий обработки данных, которые передаются куда-то за границу, и от ценовых политик, которые будут меняться только в сторону повышения. И возникает вопрос: точно ли нам, техническим писателям, для всех задач нужны самые мощные модели? Нельзя ли подойти иначе к внедрению агентов и перестать воспринимать их в роли технического писателя с кремниевыми мозгами, решающего наши задачи в тех же условиях, что и мы, а вместо этого перестроить процессы, в которых они используются? В таком случае можно было бы отказаться от автоматизации роли и начать автоматизировать отдельные операции с соответствующим снижением требований к моделям, вплоть до возможности в будущем использовать self-hosting. В последние месяцы я активно пытаюсь для себя ответить на этот вопрос, опираясь на опыт коллег из других команд, например, про организацию поиска по всей внутренней документации Яндекса. Я подумал, что если с помощью грамотной обвязки и YandexGPT на тот момент у коллег получилось построить пои

Прочитал «Если ты — технический писатель» Кати Ушаковой Наконец дошли руки до книги @ringova, которую я заказал ещё из первого тиража. Книга мне понравилась по соотношению объема и пользы — чтение, запись заметок и написание этого поста заняли у меня 4 часа, требующихся на дорогу до Москвы в Сапсане. Я читал эту книгу в первую очередь как ментор, чтобы найти какую-нибудь универсальную рекомендацию для тех, кто хочет вырасти сам и помочь правильно настроить процессы в своих компаниях. Есть несколько причин, по которым я хочу похвалить эту книгу. Первая и главная — она действительно современная. Это видно по языку, включая сленг и отсылки, но что важнее — в центре внимания документация, которая изначально создается в веб-формате, распространяется в онлайне и существует в актуальной продуктовой среде, например опирается на CJM. Вторая причина связана с первой. Книга предлагает взгляд на суть работы техписа, который мне близок. В первых шести главах совсем немного внимания уделено текстам как таковым — вместо этого разбираются разные целевые аудитории, гипотезы, исследования, способы работы с информацией и так далее. Это вещи, из-за которых прочитанное понравилось именно мне (ещё, конечно, обзор метрик, неприятие FAQ как формата современной документации и лишь одно использование аббревиатуры «ИИ» за всю книгу!). А вот джуниорам и мидлам я рекомендовал бы её из-за количества практических рекомендаций, которых там много практически на любой случай и в любых формах. Есть, правда, и неожиданные моменты. Совсем начинающие могут быть удивлены тем, что чек-лист для ревью с базовыми пунктами встречается на 98-й странице, а рекомендации по анализу логов поведения пользователей и А/Б-тестированиям — на 51-й. Я предполагаю, что это может быть хорошим заделом для повторного прочтения в будущем, тем более что книга сама по себе совсем небольшая — 122 страницы прочитает любой писатель. Короче, рекомендую. Не так много про нас пишут в целом, а про то, как действительно обстоят д

Выложил в опенсорс свой агентский пресет для создания документации https://github.com/AlexJameson/agent-user-doc-preset В этом августе исполняется год с момента, когда я впервые показал команде, на что могут быть способны агенты в плане создания документации. Вероятно, это была самая нелепая демонстрация за всю историю — в прямом эфире я в течение нескольких минут набирал промпт, который должен был заменить фрагмент одного регулярного выражения, и ждал окончания работы. В процессе пошло не так абсолютно всё, а результат оказался закоммичен не в ту ветку. С тех пор я многому научился, много сделал сам и помог со множеством запросов, в которых была одна и та же тема — как объяснить агентам, что нужно для создания хорошей доки. Интересно, что этот вопрос беспокоит не только техписов, но и других специалистов — я окончательно решил допилить свой пресет до готового состояния в ходе дискуссии в чате канале Ивана Бегтина. В общем, я сформировал набор из двух скиллов и одного agent definition, которые, на мой взгляд, закрывают минимальные потребности большинства проектов. Я противник подборок типа Superpowers, которые по умолчанию забивают контекст десятками скиллов и целятся во все возможные юзкейсы сразу. Мой пресет работает иначе, создавая фундамент, который можно потом достроить: 1. Самая важная часть пресета — навык scan-user-docs, который анализирует содержимое репозитория и фиксирует контракты в виде Markdown KV. Это обычный маркдаун, в котором есть понятная структура данных, адаптированная для чтения как агентами, так и людьми. При сканировании он определяет размер репозитория и примерный тип, то есть разделяет продуктовую документацию с условными репозиториями с кодом, где дока — один README. Результат записывается в виде трёх контрактов — STRUCTURE.md, TOOLING.md и STYLE.md, которые потом можно расширять и изменять по своему усмотрению. 2. Навык maintain-user-docs призван дать агентам минимальное руководство по тому, как в принципе создавать документацию. А