Инфраструктура меняется; документация отстаёт, если не встроена в процесс. Что фиксировать и где хранить — решает, смогут ли новички и чат по базе знаний давать ответы по актуальным данным.
Инвентарь сервисов можно хранить в README.md или в docs/services/*.md рядом с репозиторием — тогда пайплайн индексации подхватывает изменения вместе с кодом.
Что писать
Схема окружений и сервисов (что где крутится, кто за что отвечает); регламенты деплоя и отката; runbook'и по типичным инцидентам (падение сервиса, нехватка места, сетевые сбои); описание конфигов и переменных окружения. Имеет смысл завести шаблон runbook'а: цель, предусловия, шаги, откат, контакты.
| Тип документа | Назначение | Пример |
|---|---|---|
| Схема | Окружения, сервисы, владельцы | staging/prod, кто за что отвечает |
| Регламент | Деплой, откат, код-ревью | Процедура выката в prod |
| Runbook | Инциденты, пошаговые действия | Падение сервиса X, эскалация |
| Конфиги и переменные | Описание настроек | README в репо, env-переменные |
Формат и место
Markdown или Confluence/Notion; код и конфиги — в Git с README. Единый источник истины, обновление при изменении инфраструктуры.
Связка с базой знаний
Если документация индексируется в RAG, чат по архиву сможет отвечать на вопросы «как у нас настроен X» по вашим текстам. Актуальность документов влияет на качество ответов.
Минимум: схема, регламенты деплоя и отката, два-три runbook'а по частым сбоям.
Практики применения
- Фиксируйте «что где крутится», владельцев, процедуры деплоя и отката; минимум — схема и 2–3 runbook'а.
- Индексируйте в RAG — чат ответит «как у нас настроен X» с цитатами из архива.
Практика с библиотекой Adminica
Тема «Документирование инфраструктуры» лучше всего раскрывается на ваших материалах: кураторская библиотека плюс документы профиля и org-библиотека (если подключена). Задайте в чате конкретный вопрос, проверьте блок источников и при необходимости уточните формулировку — так RAG даёт воспроизводимый ответ, а не общий пересказ.
Короткий чек-лист
- Один главный вопрос за сообщение; контекст — во вложении или ссылке на запись архива.
- После обновления документов дождитесь индексации, прежде чем сравнивать ответы.
- Для командных регламентов храните master-копию в согласованном разделе базы знаний.
Тарифы и on-prem зависят от контура; начните с чата на своих данных и оцените качество по цитатам, а не только по гладкости текста.
Кратко: что где крутится, кто владелец, как деплоить и откатывать. Документация рядом с кодом; индексация в RAG — чат по архиву отвечает «как у нас настроен X».