# Ведение документации

Документация объясняет систему независимо от размещения исходного кода.
За актуальность затронутого объяснения отвечает автор изменения предметной
области; проверка сопоставляет изложение с фактическим поведением и принятыми
решениями. Ответственность подсистем описана в [карте возможностей](../features/README.md).

## Владельцы фактов

| Тип знания | Где объясняется | Граница достоверности |
| --- | --- | --- |
| Устройство и взаимодействие системы | [Обзор](../architecture/system-overview.md) | Описывает существующие подсистемы, данные и потоки |
| Наблюдаемое поведение | [Возможности](../features/README.md) | Сценарий, инвариант, ошибка и ограничение объясняются здесь полностью |
| Значение терминов | [Глоссарий](../architecture/domain-glossary.md) | Одно определение, ссылки из связанных сценариев |
| HTTP-контракт | [HTTP API](../architecture/http-api.md), публичный OpenAPI backend | Объяснение семантики не создаёт второй независимо редактируемый wire contract |
| Причины значимого решения | [ADR](../adr/README.md) | Контекст, решение и последствия относятся к указанному статусу решения |
| Окружение и восстановление | [Локальное окружение](local-workspace.md) | Предпосылки и ограничения описаны без знания устройства репозиториев |
| Принципы сопровождения | [Engineering governance](engineering-governance.md) | Объясняют согласованность и доказательства результата |
| Гипотезы и внешние наблюдения | [Исследования](../research/README.md) | Рекомендация не означает реализованную возможность |
| Результаты прежних проверок | [Исторические свидетельства](README.md#исторические-свидетельства) | Действительны для состояния и условий своего времени |

Поведенческие требования и предложения изменений могут отдельно согласовываться
в OpenSpec. Их роль описана [здесь](openspec-authority-and-lifecycle.md);
понимание текущего сценария не требует доступа к хранилищу спецификаций.

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

## Куда поместить знание

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

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

## Содержание страницы

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

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

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

## Обновление вместе с кодом

| Что изменилось в системе | Какое знание затронуто |
| --- | --- |
| Сценарий, инвариант, ошибка или восстановление | Объяснение возможности и её ограничений |
| Ответственность, внешний источник или поток данных | Обзор, схема и причина значимого решения |
| Значение понятия | Глоссарий и связанные сценарии |
| Окружение, диагностика или граница проверки | Материалы сопровождения |
| Новая возможность | Карта возможностей и тематический индекс |
| Только внутреннее устройство без изменения описанных знаний | Изменение документации может не требоваться |

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

## Проверка

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

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