89 lines
9.1 KiB
Markdown
89 lines
9.1 KiB
Markdown
# Ведение документации
|
|
|
|
Документация объясняет систему независимо от размещения исходного кода.
|
|
За актуальность затронутого объяснения отвечает автор изменения предметной
|
|
области; проверка сопоставляет изложение с фактическим поведением и принятыми
|
|
решениями. Ответственность подсистем описана в [карте возможностей](../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 и архитектура не изменены редакторским пересказом. Непонятный смысл
|
|
внешней ссылки отмечается для ручной проверки, а не восполняется догадкой.
|
|
Успешная синтаксическая проверка не доказывает актуальность знания.
|