llmdocsсправочник разработчика

Документация для ИИ: как подготовить

Материал из llmdocs — справочник разработчика
Портал: LLM, агенты, MCP
Документация для ИИ: как подготовить
Цельдокументация, которую одинаково хорошо читают люди и языковые модели
ФорматыMarkdown-копии страниц, llms.txt, llms-full.txt
Доступ для агентовMCP-серверы документации, поиск, API
Принципысамодостаточные разделы, явный контекст, проверяемые примеры, актуальность
Связанные подходыDiátaxis, docs-as-code, RAG

Документация для ИИ — набор практик, которые делают техническую документацию удобной не только для людей, но и для языковых моделей и агентов. Всё больше разработчиков узнают, как пользоваться библиотекой или API, не со страницы сайта, а из ответа ассистента или агента для кода, который сам ищет и читает документацию. Если документация плохо доступна моделям, они опираются на устаревшие знания из обучающих данных и чаще ошибаются.

Хорошая новость: почти всё, что помогает моделям, помогает и людям — ясная структура, полные примеры, явный контекст.

Почему модели читают документацию иначе

  • Нет навигации и вёрстки. Модель получает текст страницы — часто вместе с меню, рекламой, скриптами и куками, — и всё это тратит контекст.
  • Фрагменты без окружения. Системы RAG режут документы на фрагменты, и фрагмент «Затем вызовите init() с этим параметром» без заголовка и соседних абзацев теряет смысл.
  • Буквальность. Модель воспроизведёт пример кода дословно — включая устаревший импорт или пропущенный шаг.
  • Знания из обучения. Модель «помнит» старые версии API и смешивает их с новыми, если документация не говорит явно, что изменилось.

Форматы для машин

Markdown-версии страниц

Публикуйте рядом с каждой HTML-страницей её чистую версию в Markdown — например, по тому же адресу с расширением .md. Markdown сохраняет структуру (заголовки, списки, таблицы, код с указанием языка) и при этом в несколько раз компактнее HTML (см. Markdown как формат для LLM). Генераторы статических сайтов легко выдают обе версии из одного источника (Статический сайт и генераторы (SSG)).

llms.txt

Файл llms.txt в корне сайта — карта документации для моделей: название проекта, краткое описание и список ключевых страниц со ссылками на Markdown-версии и пояснением в одну строку.[1] Часто рядом кладут llms-full.txt — всю документацию одним файлом для загрузки в контекст целиком.

# Acme SDK

> Python-библиотека для работы с API платёжного сервиса Acme.

## Документация
- [Быстрый старт](https://docs.acme.dev/quickstart.md): установка и первый платёж
- [Аутентификация](https://docs.acme.dev/auth.md): ключи API и OAuth
- [Ошибки](https://docs.acme.dev/errors.md): коды ошибок и повторы

## Optional
- [История изменений](https://docs.acme.dev/changelog.md)

Доступ для агентов

Агенты всё чаще получают документацию не по ссылке, а через инструменты: MCP-сервер документации даёт поиск и чтение страниц по запросу (Model Context Protocol (MCP)).[4] Так агент берёт только нужный раздел актуальной версии, не загружая весь сайт.

Как писать

  1. Самодостаточные разделы. Каждый раздел должен быть понятен без чтения предыдущих: повторите в начале, о каком продукте и версии идёт речь, а не полагайтесь на «как описано выше». Это напрямую улучшает поиск по фрагментам; та же идея лежит в основе подхода Contextual Retrieval, где к каждому фрагменту добавляется краткий контекст документа.[3]
  2. Описательные заголовки. «Повтор запросов при ошибке 429» вместо «Дополнительно». Заголовок — главный сигнал для поиска и нарезки на фрагменты (Чанкинг документов).
  3. Полные, проверяемые примеры. Код с импортами, установкой зависимостей и ожидаемым выводом; примеры прогоняются в CI, чтобы не устаревали.
  4. Явные версии и изменения. Указывайте, с какой версии доступна функция, что устарело и чем заменить. Страница миграции «было → стало» особенно ценна для моделей с устаревшими знаниями.
  5. Однозначные определения. Термины определяются один раз и используются единообразно; синонимы для одного понятия путают и людей, и модели.[5]
  6. Типы документов не смешиваются. Разделение на обучающие материалы, практические инструкции, справочник и объяснения (подход Diátaxis) помогает и человеку, и модели найти нужный вид информации.[2]
  7. Ограничения и ошибки. Пишите, чего библиотека не умеет и какие ошибки бывают, — иначе модель додумает.

Технические детали

  • Чистый CommonMark с таблицами и блоками кода с указанием языка; без нестандартных расширений, которые превращаются в мусор вне вашего сайта.[6]
  • Стабильные URL и редиректы со старых адресов — модели и поисковые индексы помнят старые ссылки.
  • Не закрывайте документацию от ботов без необходимости: проверьте robots.txt и защиту от ботов, которые могут блокировать агентов (см. robots.txt и sitemap).
  • Справочник API — из машиночитаемого описания (OpenAPI), чтобы он не расходился с реальностью.
  • Дата обновления и версия на каждой странице.

Как проверить

Лучший тест — спросить модель. Подайте ей Markdown-версию раздела или подключите MCP-сервер и попросите решить типичную задачу пользователя: установить библиотеку, сделать первый запрос, обработать ошибку. Ошибки модели показывают, где документация неполна или двусмысленна. Набор таких задач можно запускать регулярно как тесты документации (см. Оценка LLM (evals)).

Пример

Эта вики устроена по описанным принципам: каждая статья хранится в Markdown с метаданными, сайт публикует HTML и Markdown-копии всех страниц, файлы llms.txt и llms-full.txt, а статьи написаны как самодостаточные разделы со ссылками на первоисточники. Похожий подход используют справочники tldr-pages — короткие страницы единого формата с проверяемыми примерами.

См. также

Источники

  1. llms.txt — предложение стандарта (Jeremy Howard, 2024)
  2. Diátaxis — систематический подход к технической документации
  3. Anthropic — Introducing Contextual Retrieval (2024)
  4. Model Context Protocol — Specification
  5. Google developer documentation style guide
  6. CommonMark Spec
Категории: