ADR-0001: Документационный каркас MkDocs

Статус

Accepted

Контекст

До внедрения текущего подхода документация была распределена между README и wiki, без единого стандарта API-контрактов и без автоматической проверки качества.

Решение

Принят единый документационный сайт на MkDocs + Material с:

• жесткой nav-структурой;
• унифицированными шаблонами страниц сервисов;
• диаграммами Mermaid;
• CI-проверкой сборки в strict-режиме.

Альтернативы

• Оставить wiki как основной источник (отклонено из-за слабой формализации).
• Генерировать только API-спеку (отклонено, так как нужен полный архитектурный и операционный контур).

Последствия

Положительные:

• повышение трассируемости решений;
• единый формат эксплуатационной и архитектурной информации;
• проверяемость документации в CI.

Отрицательные:

• рост объема поддержки документации;
• необходимость дисциплины обновлений при любом изменении API/моделей.