Документация для людей и ИИ

Обычно начальники хотят знать правду.

Роберт Мартин — «Чистый код»

Один документ читают человек, поиск и модель, сохраняя структуру, версию и источник. — Communication Engineering · AI-ready docs

Документация всё чаще имеет несколько получателей: человек читает страницу, поиск индексирует её, 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 в документах;
сохранение прав доступа;
корректный отказ.

Один и тот же пробел часто обнаруживается обоими способами.

Chunk review

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