На Хабре опубликован перевод подробного гайда от Kapa AI по созданию документации, оптимизированной под AI-системы. Ключевая идея: качественная документация для ИИ — это просто хорошая, структурированная и самодостаточная документация. Она улучшает не только опыт пользователей, но и качество генерации ответов в RAG-системах.

Разобран процесс обработки документации в типичной AI-инфраструктуре (Retriever → Vector DB → Generator), а также описаны критически важные принципы:

• Разделение контента на семантически связанные фрагменты (chunking)
• Использование HTML и Markdown вместо PDF, отказ от сложных JS-интерфейсов
• Семантическая ясность заголовков и URL
• Текстовые альтернативы для визуального контента
• Избегание контекстных зависимостей и неявных знаний

Приведены десятки примеров анти-паттернов и «до/после» решений: от ошибок с зависимостью от визуального макета до потерь при фрагментировании контента. Финальный вывод — документация, понятная ИИ, в первую очередь должна быть понятна человеку: структурирована, контекстна, предсказуемо оформлена. Это становится особенно важно в эпоху LLM-интерфейсов и self-service-помощников.