Всем привет!

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

У себя в телеграм-канале делюсь сжатыми и структурированными саммери статей.

Сегодняшний перевод отличного гайда по документации для AI от Kapa AI (AI-ассистент для технической документации).

Рекомендации будут полезны всем, кто работает с документацией для ИИ, не только для разработки (например, при загрузке данных в папку GPT).
Если коротко — качественная документация для ИИ это просто хорошая документация: чем чётче и структурированнее контент, тем лучше его воспринимают все, не только ИИ модели. С качественной документацией создается цикл: понятная структура улучшает ответы AI → ответы выявляют пробелы для дальнейшего улучшения → исправлять пробелы проще в качественной документации.

---

Почему качество документации имеет значение

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

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

Как системы ИИ обрабатывают вашу документацию

Этот процесс включает три основных компонента:

• Retriever (Извлекатель): Ищет контент, соответствующий вопросу пользователя, в ваших источниках знаний.

• Vector database (Векторная база данных): Хранит ваш контент в поисковом формате, что обеспечивает быстрое и точное извлечение.

• Generator (Генератор): LLM, который использует извлечённый контент для создания полезных ответов.

После подключения источников знаний информация проходит через определённый процесс:

1. Ingestion (Приём): Контент делится на фрагменты (более мелкие, сфокусированные разделы) и сохраняется в векторной базе данных.

2. Query processing (Обработка запросов): Когда пользователи задают вопросы, система преобразует их вопрос в поисковый формат.

3. Retrieval (Извлечение): Система находит наиболее релевантные фрагменты из вашей документации.

4. Answer generation (Генерация ответа): LLM использует эти фрагменты в качестве контекста для генерации ответа.

На этапах, которые ИИ проходит для потребления вашего контента, стоит выделить некоторые особенности написания и структурные шаблоны, которые могут негативно влиять на то, насколько хорошо ваш контент понимается:

• Системы ИИ работают с фрагментами: Они обрабатывают документацию как дискретные, независимые части, а не читают её как непрерывное повествование.

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

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

• Они не могут выводить неуказанную информацию: В отличие от людей, которые могут делать предположения, системы ИИ могут работать только с явно документированной информацией.

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

Хотя ИИ действительно прекрасно работает с неструктурированным контентом, верно и то, что информация, написанная и структурированная с учётом извлечения, может значительно улучшить качество интерфейса "Спросить ИИ" к вашим источникам знаний.

Почему фрагментирование (chunking) необходимо

В идеале фрагментирование не было бы необходимым, и ИИ мог бы постоянно держать в контексте всю вашу базу знаний. К сожалению, это непрактично. Не только из-за ограничений токенов, но и потому, что LLM работают значительно лучше при наличии оптимизированных, сфокусированных контекстов. Большой или чрезмерно широкий контекст увеличивает вероятность того, что модель упустит или неверно истолкует критическую информацию, что приведёт к снижению точности и менее связным результатам.

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

Быстрые советы по оптимизации контента

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

1. Используйте стандартизированный семантический HTML

Для веб-источников убедитесь в правильном и семантическом использовании HTML-элементов, таких как заголовки ( <h1>, <h2>), списки ( <ul>, <ol>) и таблицы ( <table>). Семантический HTML обеспечивает чёткую структуру документа, улучшая точность фрагментирования и извлечения контента.

Пример

<h2>How to enable webhooks</h2>
<ol>
  <li>Log in to your CloudSync dashboard.</li>
  <li>Navigate to Settings &gt; Webhooks.</li>
  <li>Toggle webhooks to "Enabled".</li>
</ol>

Что ещё более важно, избегайте неправильного использования элементов. Неправильно расположенный элемент <h2>, например, может иметь серьёзные последствия для того, как машина анализирует ваш контент.

2. Избегайте PDF, предпочтительнее HTML или Markdown

PDF-документы часто имеют сложную визуальную компоновку, что затрудняет машинный анализ. Перенос контента из PDF в HTML или Markdown значительно улучшает извлечение текста и качество поиска.

3. Создавайте контент, удобный для краулеров

Упростите структуру страниц, уменьшив или устранив пользовательские элементы UI, динамический контент на JavaScript и сложные анимации. Чёткая, предсказуемая HTML-структура облегчает индексирование и анализ.

Замените сложные виджеты JavaScript альтернативами в виде простого текста или простыми интерактивными элементами.

4. Обеспечьте семантическую ясность

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

Пример осмысленного URL

✅ Хорошо: /docs/cloudsync/setup-webhooks
❌ Плохо: /docs/page12345

5. Предоставляйте текстовые эквиваленты для визуальных элементов

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

Пример

![Диаграмма архитектуры системы](architecture.png)

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

6. Сохраняйте простые макеты

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

Проблемы проектирования контента для ИИ

Этот раздел более подробно рассматривает распространённые анти-паттерны в проектировании контента, которые могут создавать проблемы для систем ИИ. Эти проблемы часто возникают из-за того, как информация организована, контекстуализирована или предполагается, а не из-за того, как она отформатирована. Каждый пример выделяет конкретный проблемный шаблон, почему он вызывает проблемы для ИИ, и как переписать или реструктурировать ваш контент, чтобы избежать его.

Контекстные зависимости

Проблема: Документация, которая разбрасывает ключевые детали и определения по нескольким разделам или абзацам, создаёт проблемы, когда контент делится на фрагменты. Когда критически важная информация отделена от своего контекста, отдельные фрагменты могут стать двусмысленными или неполными.

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

• Слишком длинные разделы делятся по границам абзацев или предложений.

• Слишком короткие разделы объединяются с соседним контентом.

• Размеры фрагментов должны быть сбалансированы для оптимальной производительности извлечения.

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

Рассмотрим этот (упрощённый) проблемный пример:

Authentication tokens expire after 24 hours by default.

The system provides several configuration options for different environments.

When implementing the login flow, ensure you handle this appropriately.

Когда этот контент фрагментируется, среднее предложение о параметрах конфигурации может привести к тому, что алгоритм фрагментирования отделит информацию об истечении срока действия токена от рекомендаций по реализации. В результате фрагмент, содержащий "When implementing the login flow, ensure you handle this appropriately" (При реализации процесса входа в систему убедитесь, что вы правильно это обрабатываете), теряет решающий контекст о том, что означает "это" и о конкретном 24-часовом сроке.

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

Authentication tokens expire after 24 hours by default. When implementing the
login flow, ensure you handle token expiration by refreshing tokens before the
24-hour limit or implementing proper error handling for expired token
responses.

The system provides several configuration options for different environments,
including custom token expiration periods.

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

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

Пробелы в семантической обнаруживаемости

Проблема: Если важные термины или концепции отсутствуют во фрагменте, этот фрагмент не будет извлечён для соответствующих запросов, даже если он содержит именно ту информацию, которая нужна.

## Configure timeouts

Configure custom timeout settings and retry logic for improved reliability in
production environments. Access these options through the admin panel.

Если пользователь спросит "Как настроить тайм-ауты CloudSync?", этот фрагмент может быть не извлечён, потому что "CloudSync" не встречается в тексте.

Решение: Установите единую терминологию для уникальных концепций вашего продукта и систематически используйте её. Включайте конкретные названия продукта или функций при документировании функциональности.

## Configure CloudSync timeouts

Configure custom CloudSync timeout settings and retry logic for improved
reliability in production environments. Access these options through the
CloudSync admin panel.

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

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

Предположения о неявных знаниях

Проблема: В отличие от людей (читателей документации), которые могут опираться на внешние знания или делать разумные выводы, ИИ работает только с предоставленной информацией.

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

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

До

## Setting up webhooks

Configure your endpoint URL in the dashboard and test the connection.

После

## Setting up CloudSync webhooks

Before configuring webhooks, ensure you have:

- A publicly accessible HTTPS endpoint
- Valid SSL certificate
- CloudSync API credentials

Configure your endpoint URL in the CloudSync dashboard under Settings >
Integrations, then use the "Test connection" button to verify setup.

Ищите инструкции, которые предполагают знакомство с инструментами или интерфейсами, или ссылаются на "стандартные" конфигурации без объяснения.

Зависимости от визуальной информации

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

Пример: Информация, которая полностью зависит от графического элемента

See the diagram below for the complete API workflow:
![Complex flowchart showing 8-step process](workflow.png)

Follow these steps to implement the integration.

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

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

## CloudSync API workflow

The CloudSync integration follows this workflow:

1. **Authentication**: Send API credentials to `/auth/token` endpoint
2. **Validation**: System validates credentials and returns access token
3. **Data preparation**: Format your data according to CloudSync schema
4. **Upload request**: POST data to `/sync/upload` with access token
5. **Processing**: CloudSync validates and processes the data
6. **Status check**: Poll `/sync/status/{job_id}` for processing updates
7. **Completion**: Receive confirmation when sync completes
8. **Error handling**: Handle any validation or processing errors

![Диаграмма рабочего процесса API](workflow.png)
_Визуальное представление шагов рабочего процесса выше_

Информация, зависящая от макета

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

Сложные или плохо структурированные сравнительные таблицы с объединёнными заголовками и визуальными группами становятся двусмысленными при преобразовании в простой текст:

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

## CloudSync pricing plans

### Basic Plan

- 5 users
- 1GB storage
- Email support
- API limits: 100 requests/hour, basic endpoints only

### Standard Plan

- 25 users
- 10GB storage
- Phone support
- API limits: 1,000 requests/hour, all endpoints

### Enterprise Plan

- Unlimited users
- Unlimited storage
- 24/7 dedicated support
- API limits: No rate limit, all endpoints plus webhooks

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

Организация контента

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

Иерархическая информационная архитектура

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

Эта иерархия включает в себя несколько слоёв контекста: пути URL, заголовки документов и заголовки разделов. Эти элементы работают вместе, чтобы создать контекстное понимание для фрагментов контента после того, как они отделены от своего первоначального местоположения.

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

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

• Семейство продуктов: Какая область продукта или услуги.

• Название продукта: Конкретное название продукта или функции.

• Информация о версии: Если применимо.

• Специфика компонента: Подфункции или модули.

• Функциональный контекст: Чего пытается достичь пользователь.

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

Самостоятельные разделы

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

Сравните два подхода к одной и той же информации:

Зависимый от контекста

## Updating webhook URLs

Now change the endpoint to your new URL and save the configuration.

Самостоятельный

## Updating webhook URLs

To update webhook endpoints in CloudSync:

1. Navigate to Settings > Webhooks in your CloudSync dashboard
2. Select the webhook you want to modify
3. Change the endpoint URL to your new address, and click Save

Самостоятельная версия работает при извлечении в виде изолированного фрагмента, потому что она включает в себя основной контекст: какая система (CloudSync), где найти настройку (Settings > Webhooks) и полные шаги. Версия, зависимая от контекста, предполагает, что читатель знает, что означает "endpoint" и где он находится в интерфейсе.

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

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

Контекст ошибок с решениями

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

При документировании шагов по устранению неполадок цитируйте точные сообщения об ошибках и описывайте наблюдаемые симптомы наряду с решениями.

Общее устранение неполадок

## Connection problems

If the connection fails, check your network settings and firewall configuration.

Специфическое устранение неполадок

## CloudSync connection problems

### Error: "Connection timeout after 30 seconds"

This error occurs when CloudSync cannot reach the…

### Error: "Authentication failed (401)"

This indicates invalid or expired credentials…

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

Заключение

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

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

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