# General Translation Blog: Переписываем документацию для людей и агентов
URL: https://generaltranslation.com/ru/blog/rewriting-our-docs.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: Как мы выстроили опыт чтения с помощью руководства по стилю на 13 000 слов и структурировали документацию так, чтобы её было удобно читать агентам.
Authors: Taylor Fang
Published: 2026-09-14

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

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

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

[Наша документация](https://generaltranslation.com/en-US/docs/overview/get-started) росла естественным образом по мере того, как платформа обрастала поддержкой новых фреймворков и интеграций. Но структура, порядок изложения и язык постепенно начали расходиться.

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

Для удобства чтения агентами мы также отдаём [`llms.txt`](https://generaltranslation.com/llms.txt) и [`llms-full.txt`](https://generaltranslation.com/llms-full.txt) для машиночитаемого обнаружения и извлечения содержимого, а каждую страницу документации — в виде исходного Markdown: достаточно добавить `.md` или `.mdx` к её URL. У нас есть страница документации [для агентов, работающих с кодом](https://generaltranslation.com/en-US/docs/overview/for-coding-agents) с готовым файлом `AGENTS.md`, который объясняет агенту, как правильно выполнить настройку, работать с продуктом и переводить, — а также размещённый у нас MCP-сервер и машиночитаемая спецификация OpenAPI.

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

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

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

* Статья Ли Робинсона о [документации](https://leerob.com/docs). **«Сделайте первое знакомство простым и раскрывайте сложность постепенно».** Среди его десяти принципов: быстрая, читаемая, дружественная к ИИ, отточенная, отзывчивая. И, конечно же, локализованная. (Мы и правда работали с Ли над [локализацией документации Cursor](https://www.linkedin.com/posts/leeerob_just-shipped-new-docs-for-cursor-been-hacking-activity-7374285675900297216-veY1/)!)
* Статья Fuma Nama о [документации](https://www.fuma-nama.dev/blog/good-docs). Он рекомендует простой стиль изложения и **более логичную структуру** — с выделением жирным, заголовками, гиперссылками, списками и таблицами. Fuma также утверждает, что для восприятия читателем навигация может быть важнее самого содержания. ([Подробнее](https://generaltranslation.com/en-US/blog/fuma-nama) о философии Fuma — в нашем интервью.)
* Статья Девин Логан о [документации, готовой к работе с агентами](https://buildwithfern.com/post/agent-friendly-docs). Девин пишет, что **новая норма — это обращение пользователей к документации через агентов**. Она описывает, как сделать документацию понятной для ИИ: на уровне содержания материал должен объяснять устройство систем и давать исполнимые шаги; на уровне платформы страницы должны легко находиться и быть очищены от лишнего для агентов.
* Мы внимательно изучили документацию для разработчиков, которую любим: [Linear](https://linear.app/docs) — за ясность и простоту, [Replicate](https://replicate.com/docs) — за понятную иерархическую навигацию, [shadcn/ui](https://ui.shadcn.com/docs) — за красивый дизайн, [Next.js](https://nextjs.org/docs) — за язык, близкий разработчикам, и возможности для сообщества, [Convex](https://docs.convex.dev/home) — за восхитительную графику, [Stripe](https://docs.stripe.com) — за встроенную функциональность, и многие другие.

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

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

![Три вопроса пользователя, каждый из которых ведёт к своему типу страницы документации: Quickstart, Guides или Reference](/static/blogs/rewriting-docs-spine.png?v=20260914-1722)

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

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

Сам сайт документации построен на [Fumadocs](https://www.fumadocs.dev), с создателем которого мы недавно [побеседовали](https://generaltranslation.com/en-US/blog/fuma-nama) о его взглядах на красивый и композиционный опыт чтения.

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

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

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

![Боковая панель документации до и после редизайна, реорганизованная вокруг разделов Overview, Platform, фреймворков и Integrations](/static/blogs/rewriting-docs-sidebar.png?v=20260914-1722)

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

![Компонент Next steps, связывающий страницу с четырьмя наиболее близкими руководствами](/static/blogs/rewriting-docs-frameworks.png?v=20260914-1722)

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

![Общий блок кода с вкладками фреймворков React, Next.js, TanStack Start и React Native](/static/blogs/rewriting-docs-next-steps.png?v=20260914-1722)

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

![Страница Page not found со ссылками на пять наиболее близких страниц документации](/static/blogs/rewriting-docs-not-found.png?v=20260914-1722)

## Простой язык

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

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

<Callout type="info" icon=" " className="w-full max-w-none rounded-md border-0 bg-fd-muted p-5 shadow-none [&>div:first-child]:hidden [&_p]:my-3! [&_ul]:my-3! [&_li]:my-3! [&_p]:leading-snug! [&_li]:leading-snug!">
  **Аудитория**

  Пишите для читателя конкретной страницы и подбирайте глубину изложения и лексику под него:

  * Технические страницы для разработчиков. Читатели — разработчики, интегрирующие SDK, CLI или API. Будьте точны в описании типов, параметров, заголовков, значений по умолчанию и поведения при ошибках; показывайте готовые к запуску примеры. Следите за тем, чтобы документация была машиночитаемой для LLMs и агентов.
  * Нетехнические продуктовые страницы: dashboard и Locadex. Читатели — менеджеры по локализации, переводчики и продакт-менеджеры, работающие в интерфейсе dashboard. Начинайте с результатов и действий в интерфейсе; объясняйте понятия простым языком.

  Правила ясности для любой аудитории:

  <Check className="inline size-4 align-[-3px] text-green-600 dark:text-green-500" strokeWidth="3" /> Сначала объясните, что это и зачем, и только потом — как.

  <Check className="inline size-4 align-[-3px] text-green-600 dark:text-green-500" strokeWidth="3" /> Одна мысль на предложение; отдавайте предпочтение коротким предложениям.

  <Check className="inline size-4 align-[-3px] text-green-600 dark:text-green-500" strokeWidth="3" /> Давайте определение термину при первом упоминании и расшифровывайте сокращения при первом использовании.

  <X className="inline size-4 align-[-3px] text-red-600 dark:text-red-500" strokeWidth="3" /> Не используйте понятие, продуктовый термин или настройку до того, как они введены.

  <X className="inline size-4 align-[-3px] text-red-600 dark:text-red-500" strokeWidth="3" /> Избегайте необъяснённого жаргона. Если без термина не обойтись, а объяснить его одним предложением слишком сложно, дайте ссылку на его определение.
</Callout>

Мы также написали страницы под конкретные типы пользователей. Тем, кто только начинает знакомиться с локализацией, страница [Key concepts](https://generaltranslation.com/en-US/docs/overview/key-concepts) объясняет базовые понятия простым языком: интернационализация, локализация, перевод, locales и context. Тем, кто работает преимущественно с агентами, страница [Using coding agents](https://generaltranslation.com/en-US/docs/overview/for-coding-agents) указывает агентам путь к нашей машиночитаемой документации, MCP-серверу и готовому к использованию руководству `AGENTS.md` (подробнее об этом ниже).

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

Как уже писали [многие](https://www.mintlify.com/blog/state-of-ai) [источники](https://blog.cloudflare.com/markdown-for-agents/), сегодня агенты составляют большинство читателей документации. Поэтому удобство для LLM — приоритет первого порядка. Многие принципы читаемости и структурирования одинаково применимы к контенту и для людей, и для агентов; однако агентам нужны специализированные возможности **обнаружения, извлечения и доступа к инструментам**.

Готовность к работе с агентами мы проектировали, опираясь на [спецификацию Agent Readability](https://vercel.com/kb/guide/agent-readability-spec) от Vercel и [спецификацию AFdocs](https://afdocs.dev). Эти две спецификации отвечают на ключевые вопросы о том, как AI-агенты находят и разбирают контент. Могут ли агенты обнаружить страницы документации и сориентироваться в том, что в них описано? Могут ли они прочитать чистый markdown-контент, помещающийся в контекстное окно? Могут ли они искать, получать и использовать нужные AI-инструменты?

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

* [`llms.txt`](https://generaltranslation.com/llms.txt): индекс документации по стандарту [llmstxt.org](https://llmstxt.org) с дополнительными уровнями: [`llms-index.txt`](https://generaltranslation.com/llms-index.txt) (каждая страница), [индексы по разделам](https://generaltranslation.com/docs/react/llms.txt) и [`llms-full.txt`](https://generaltranslation.com/llms-full.txt) (полный корпус для инструментов, способных загрузить больший контекст)
* [`sitemap.xml`](https://generaltranslation.com/sitemap.xml) и [`sitemap.md`](https://generaltranslation.com/sitemap.md): машиночитаемые карты всех страниц
* Исходный Markdown для каждой страницы: добавьте `.md` или `.mdx` к любому URL документации. Распознанные AI-краулеры и агенты, отправляющие `Accept: text/markdown`, получают Markdown автоматически
* MCP-сервер (Model Context Protocol) с аутентификацией по адресу [`https://api.gtx.dev/mcp`](https://api.gtx.dev/mcp), использующий streamable HTTP
* Машиночитаемая спецификация OpenAPI по адресу [`/openapi.json`](https://generaltranslation.com/openapi.json) (и [`/openapi.yaml`](https://generaltranslation.com/openapi.yaml)), на которую ведут ссылки с каждой справочной страницы эндпоинта
* Контент, разбитый на фрагменты для RAG (retrieval-augmented generation): каждый раздел содержит законченную мысль и следует единой иерархии heading&#39;ов
* Разрешительный [`robots.txt`](https://generaltranslation.com/robots.txt), который открывает AI-краулерам доступ ко всем публичным страницам

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

![Первый рефакторинг документации: изменено 900 файлов, 31 868 добавлений и 32 249 удалений](/static/blogs/rewriting-docs-diff.png?v=20260914-1722)

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

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

![Редактирование документации в Cursor: исходный MDX рядом с предпросмотром Markdown](/static/blogs/rewriting-docs-cursor.png?v=20260914-1722)

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

Благодаря такому подходу наше [руководство по стилю документации](https://github.com/generaltranslation/content/blob/main/DOCS-SKILL.md) получилось предельно подробным и **точно отражающим наши предпочтения**: оно охватывает множество пограничных случаев и пользовательских задач и насчитывает более 830 строк и 13 000 слов. Руководство — это свод рабочих процедур, которые проверяются в CI и легко применяются агентами; в него входят как общие принципы письма, так и вполне конкретные правила и приёмы. **Кроме того, ежедневно запускается облачный агент, который синхронизирует документацию с реальным поведением продукта.** Агент ищет пробелы в покрытии, неточности и устаревшие примеры. Он разворачивает новый проект и тестирует возможности локально, а также проверяет текст на соответствие руководству по стилю.

Правила руководства по стилю похожи на [правила контекста и пользовательских промптов](https://generaltranslation.com/en-US/docs/platform/dashboard/guides/defining-context-for-translations), которые мы применяем для обеспечения качества перевода у наших клиентов.

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

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

Следите за второй частью нашего блога: в ней мы расскажем о переработке UI и взаимодействия в документации, а также о том, как мы создавали собственные визуальные элементы на [Fumadocs](https://generaltranslation.com/en-US/blog/fuma-nama).

![Панель обратной связи на каждой странице документации: изменить страницу, сообщить о проблеме на GitHub или задать вопрос](/static/blogs/rewriting-docs-footer.png?v=20260914-1722)

## Sitemap

See the full [sitemap](https://generaltranslation.com/sitemap.md) for all pages.