Documentation System¶

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

Уровни документации¶

Уровень	Где лежит	Что хранит
Навигация	docs.md, docs/index.md	входы, маршруты чтения, ссылки на модули
Архитектурные границы	docs/modules.md, docs/library-dependencies.md, docs/architecture/	ownership модулей, допустимые зависимости, правила перемещения кода
Документация модуля	`<module>/docs/`	API, lifecycle, ownership, gotchas, примеры модуля
Планы миграций	docs/plans/	временные планы, решения, чеклисты до завершения миграции
README	`<module>/README.md`	короткий вход и ссылка на полную документацию

Правила ссылок¶

Используем обычные Markdown-ссылки: [termin-gui](../termin-gui/docs/index.md).
Obsidian понимает такие ссылки и строит graph/backlinks без wiki-синтаксиса.
Wiki-ссылки [[...]] допустимы только в личных черновиках, которые не являются source of truth.
Если документ описывает модуль, он должен ссылаться на Module Map и на соседние модули, от которых зависит.

Граница модуля¶

Для каждого крупного модуля в Module Map должна быть описана граница ответственности. Если раздел становится слишком большим, его можно вынести в отдельный файл в docs/modules/.

Описание границы отвечает на вопросы:

За что отвечает модуль.
Что считается публичным API.
Какие соседние модули с ним связаны.
Какие upstream/downstream зависимости допустимы.
Куда переносить код, если он оказался не на своем уровне.
Какие документы являются source of truth.

Когда переносить документацию¶

Документ надо держать в корне docs/, если он описывает границу между несколькими модулями. Архитектурные заметки без одного владельца лежат в docs/architecture/. Документ надо держать в <module>/docs/, если он описывает внутренний API, lifecycle или практику использования одного модуля.

План миграции после завершения не должен оставаться единственным описанием текущего состояния. Итоговое устройство переносится в живую документацию, а план остается историей.

Минимальная проверка¶

Перед завершением архитектурной правки надо проверить:

обновлен ли паспорт затронутого модуля;
появились ли новые зависимости в Library Dependencies;
не остался ли новый behavior только в docs/plans/;
есть ли ссылка из ближайшего README.md или docs/index.md.