Обычно начальники хотят знать правду.
Документация всё чаще имеет несколько получателей: человек читает страницу, поиск индексирует её, RAG режет на фрагменты, агент извлекает инструкцию. Требования похожи: ясная структура, локальный контекст, точные термины и актуальность.
Автономный фрагмент
Фрагмент должен сохранять смысл вне соседнего абзаца:
- заголовок называет объект и действие;
- местоимения имеют понятный референт;
- единицы, версия и среда указаны;
- исключение находится рядом с правилом;
- ссылка ведёт к каноническому источнику.
Плохо:
Это нужно сделать до него, иначе там возникнет ошибка.
Хорошо:
Создайте idempotency key до вызова Payment API; повторный запрос без ключа может создать вторую операцию.
Структура
- один H1;
- иерархические H2/H3;
- короткое summary;
- отдельные prerequisites;
- нумерованные процедуры;
- таблицы для сравнения;
- код с языком;
- даты и версии;
- owner и status;
- связанные решения.
Не используйте визуальное выделение вместо смысловой структуры.
Chunking
Фиксированная нарезка по символам может разорвать условие и исключение. Предпочтительнее смысловые секции с разумным размером и overlap. Таблица, листинг и предупреждение могут требовать специальной обработки.
Проверяйте получившиеся chunks как отдельный интерфейс.
Каноничность
Дубликаты создают конфликт версий. Выберите источник истины и в других местах давайте ссылку или генерируемое представление. Укажите:
- status: draft/accepted/deprecated;
- valid from;
- owner;
- supersedes;
- last reviewed.
Термины
Словарь помогает людям и retrieval:
- один термин на понятие;
- синонимы перечислены;
- аббревиатура раскрыта;
- внутреннее значение отделено от общего;
- старый термин отмечен как deprecated.
Инструкции и данные
Документ может содержать команды, пользовательский ввод и цитаты. Для AI-систем важно не считать любой текст инструкцией. Маркируйте code blocks, examples, untrusted content и разрешённые действия. Технический слой должен сохранять эту границу.
Runbook говорит «перезапустите его и проверьте там». Человек знает контекст из команды, RAG возвращает фрагмент отдельно и создаёт опасную инструкцию.
ИсправлениеКаждый шаг называет сервис, среду, команду, ожидаемый результат и условие остановки. Опасная production-команда требует отдельного подтверждения.
Тестирование
Для людей:
- task-based usability;
- поиск;
- вопросы новичков;
- время до результата.
Для AI:
- retrieval набор;
- grounded answers;
- конфликт версий;
- prompt injection в документах;
- сохранение прав доступа;
- корректный отказ.
Один и тот же пробел часто обнаруживается обоими способами.
Возьми одну важную страницу и раздели по заголовкам. Прочитай каждый фрагмент отдельно: понятны ли объект, версия, действие и исключение? Исправь локальный контекст, не дублируя весь документ.
