Как мы переписали документацию для людей и агентов

Проектирование с расчётом на двух типов читателей

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

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

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

Мы решили переписать документацию с нуля, сознательно ориентируясь на удобство чтения как для людей, так и для агентов. Первый рефакторинг затронул 900 файлов (+31 868 / −32 249 строк). Мы составили руководство по стилю объёмом 13 000 слов с правилами по аудитории, структуре страницы, стилю и грамматике. Теперь документацию сопровождает ежедневный облачный агент, который проверяет её на соответствие этому руководству.

Для удобства чтения агентами мы также отдаём llms.txt и llms-full.txt для индексации сайта, а каждую страницу документации — в виде исходного Markdown: достаточно добавить .md к её URL. У нас есть страница документации для агентов, работающих с кодом с готовым файлом AGENTS.md, который объясняет агенту, как правильно выполнить настройку, работать с продуктом и переводить, — а также MCP-сервер и машиночитаемая спецификация OpenAPI.

В этой публикации мы расскажем о внесённых изменениях и о том, какие выводы сделали.

Источники вдохновения

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

• Статья Ли Робинсона о документации. «Сделайте первое знакомство простым и раскрывайте сложность постепенно». Среди его десяти принципов: быстрая, читаемая, дружественная к ИИ, отточенная, отзывчивая. И, конечно же, локализованная. (Мы и правда работали с Ли над локализацией документации Cursor!)
• Статья Fuma Nama о документации. Он рекомендует простой стиль изложения и более логичную структуру — с выделением жирным, заголовками, гиперссылками, списками и таблицами. Fuma также утверждает, что для восприятия читателем навигация может быть важнее самого содержания. (Подробнее о философии Fuma — в нашем интервью.)
• Статья Девин Логан о документации, готовой к работе с агентами. Девин пишет, что новая норма — это обращение пользователей к документации через агентов. Она описывает, как сделать документацию понятной для ИИ: на уровне содержания материал должен объяснять устройство систем и давать исполнимые шаги; на уровне платформы страницы должны легко находиться и быть очищены от лишнего для агентов.
• Мы внимательно изучили документацию для разработчиков, которую любим: Linear — за ясность и простоту, Replicate — за понятную иерархическую навигацию, shadcn/ui — за красивый дизайн, Next.js — за язык, близкий разработчикам, и возможности для сообщества, Convex — за восхитительную графику, Stripe — за встроенную функциональность, и многие другие.

Пользовательские сценарии

Мы перестроили страницы и формулировки вокруг того, чего хочет добиться пользователь, а не вокруг описания технических возможностей. Каждый раздел строится по единой схеме: Quickstart, Guides и Reference.

Заголовки руководств сформулированы как отглагольные существительные и задачи, которые нужно решить: например, «Просмотр и редактирование переводов» или «Работа с формами множественного числа и ветвлениями». Новому пользователю, который пытается пройти тот или иной workflow, не нужно гадать, какой справочный термин искать, — достаточно ввести нужное действие.

Приятный побочный эффект: наши руководства сами по себе высоко ранжируются в поиске — например, занимают первое место в Google по запросам «React managing locales», «React translating jsx», «Configuring a Vite SPA i18n», «React plurals and branches», «Translating rrweb» и многим другим.

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

Логичная и интуитивная подача

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

a) Структура. Структура и порядок нашей документации контролируются в CI: проверка фиксирует разделы верхнего уровня, чтобы новая страница вставала на своё место в существующей информационной архитектуре.

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

c) Выбор пользователя. Сайт документации запоминает выбор пользователя и автоматически отображает содержимое на последнем выбранном языке и в выбранной теме. Блоки кода также автоматически сохраняют выбранную пользователем вкладку фреймворка (React, Next.js, TanStack Start или React Native) и менеджера пакетов (npm, yarn, bun или pnpm).

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

Простой язык

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

Каждая страница адресована конкретной аудитории и написана с учётом её запросов. Из нашего руководства по стилю документации:

Мы также написали страницы под конкретные типы пользователей. Тем, кто только начинает знакомиться с локализацией, страница Key concepts объясняет базовые понятия простым языком: интернационализация, локализация, перевод, locales и context. Тем, кто работает преимущественно с агентами, страница Using coding agents указывает агентам путь к нашей машиночитаемой документации, MCP-серверу и готовому к использованию руководству AGENTS.md (подробнее об этом ниже).

Проектирование с расчётом на чтение агентами

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

Готовность к работе с агентами мы проектировали, опираясь на спецификацию Agent Readability от Vercel и спецификацию AFdocs. Эти две спецификации отвечают на ключевые вопросы о том, как AI-агенты находят и разбирают контент. Могут ли агенты обнаружить страницы документации и сориентироваться в том, что в них описано? Могут ли они прочитать чистый markdown-контент, помещающийся в контекстное окно? Могут ли они искать, получать и использовать нужные AI-инструменты?

Ключевые части нашей реализации:

• llms.txt: индекс документации по стандарту llmstxt.org с дополнительными уровнями: llms-index.txt (каждая страница), llms-scope.txt/<section> (индексы по разделам) и llms-full.txt (полный корпус для инструментов, способных загрузить больший контекст)
• sitemap.xml и sitemap.md: машиночитаемые карты всех страниц
• Исходный Markdown для каждой страницы: добавьте .md или .mdx к любому URL документации. Распознанные AI-краулеры и агенты, отправляющие Accept: text/markdown, получают Markdown автоматически
• MCP-сервер (Model Context Protocol): npm-пакет @generaltranslation/mcp для локального использования через stdio, размещённый эндпоинт по адресу https://mcp.gtx.dev (streamable HTTP, с вариантом SSE) и project-scoped эндпоинт по адресу https://api.gtx.dev/mcp с аутентификацией по API Key
• Машиночитаемая спецификация OpenAPI по адресу /openapi.json (и /openapi.yaml), на которую ведут ссылки с каждой справочной страницы эндпоинта
• Контент, разбитый на фрагменты для RAG (retrieval-augmented generation): каждый раздел содержит законченную мысль и следует единой иерархии heading'ов
• Разрешительный robots.txt: AI-краулеры никогда не блокируются

Процесс, поддержка и руководство по стилю

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

Сначала я провёл всестороннюю инвентаризацию, чтобы собрать полную опись существующей документации: 900 страниц и более 117 000 слов текста. Имея на руках указатель этого исходного материала, я перестроил содержимое по написанной вручную карте: какие разделы верхнего уровня нам нужны, как сгруппировать и упорядочить фреймворки и какова задача каждой страницы. Я написал и отредактировал показательные страницы в каждом разделе, заложив в них наши принципы ясности, простоты и поддержки пользовательского пути. Ручная часть работы заняла больше месяца сосредоточенного труда. Особенно много тестирования потребовали быстрые старты, а инженеры нашей i18n-библиотеки внесли существенные правки.

Увлекательной частью процесса стала работа прямо в Cursor с активным использованием панели предпросмотра Markdown. Все мои правки фиксировались в истории версий, так что я мог легко попросить агента обобщить мои изменения (и даже ход мысли) в принципы и правила, добавить их в наше руководство по стилю и применить ко всем страницам. Каждый раз, когда мы правим документацию — будь то структура или содержание, — мы обобщаем эти изменения и применяем их через руководство по стилю.

Благодаря такому подходу наше руководство по стилю документации получилось предельно подробным и точно отражающим наши предпочтения: оно охватывает множество пограничных случаев и пользовательских задач и насчитывает более 830 строк и 13 000 слов. Руководство — это свод рабочих процедур, которые проверяются в CI и легко применяются агентами; в него входят как общие принципы письма, так и вполне конкретные правила и приёмы. Кроме того, ежедневно запускается облачный агент, который синхронизирует документацию с реальным поведением продукта. Агент ищет пробелы в покрытии, неточности и устаревшие примеры. Он разворачивает новый проект и тестирует возможности локально, а также проверяет текст на соответствие руководству по стилю.

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

Часть 2: визуальный дизайн

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

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