Перейти к основному содержимому

Управление документацией (documentation governance) — каноничный процесс работы с документным слоем платформы

Версия: 1.0 Дата: 27.04.2026 Статус: Готов к обсуждению

Назначение документа​

Этот документ задаёт каноничный процесс управления документацией платформы Vitiana — от создания документа до его архивации. Документ является обязательным для всех участников документной работы (главный архитектор, команды разработки, команды операций, технические писатели, контракторы) и определяет:

  • роли и зоны ответственности (ownership);
  • жизненный цикл документа (create → review → publish → maintain → archive);
  • правила оформления и языка;
  • правила работы с DocMap MCP;
  • правила архивации (no-destruction principle);
  • правила связности (link graph integrity);
  • правила тезисного обоснования архитектурных решений;
  • процессы review, утверждения, обновления;
  • метрики качества документного слоя.

Документ закрывает Stage 0 development roadmap (см. roadmap.md) и является сквозным workstream S1 «Documentation governance».

Тезисное обоснование​

Тезис 1. Documentation governance — first-class дисциплина, не «писатели сделают потом».

Альтернативы: (а) документация на усмотрение каждой команды; (б) централизованная команда technical writers пишет документы; (в) каноничный процесс с распределённой ответственностью и едиными правилами.

Trade-off: вариант (а) приводит к фрагментации стиля, дублированию, противоречиям между документами разных команд; вариант (б) дорог и создаёт bottleneck — technical writers не успевают за продуктовыми циклами; вариант (в) — каноничная модель верхнеуровневых платформ (Stripe, Twilio): авторы документов — те же инженеры/архитекторы, кто принимает решения, но они работают в едином governance framework. Это масштабируется и гарантирует консистентность.

Тезис 2. Документация — ориентир, не источник истины.

Альтернативы: (а) документация — primary source (что в доке, то и работает); (б) код — primary source, документация постфактум; (в) код — single source of truth, документация — навигационный слой над ним.

Trade-off: вариант (а) приводит к ситуации «документ говорит одно, код делает другое» с длительной потерей доверия; вариант (б) — приемлем, но создаёт риск никогда не документировать; вариант (в) — каноничный подход, согласованный с реальностью платформенной разработки и явно зафиксированный в Своде законов ИИ-агента (раздел I «Код первичен»). Документация существует, чтобы помочь людям ориентироваться, не чтобы заменять собой реальность.

Тезис 3. No destruction — никогда не стираем историю.

Альтернативы: (а) удалять устаревшие документы; (б) перезаписывать документы новой версией без сохранения старой; (в) переименовывать в *-old-YYYY-MM-DD.md со статусом Черновик.

Trade-off: вариант (а) теряет аудитный след архитектурных решений, что недопустимо для compliance (SOC 2, ISO 27001 требуют document version history); вариант (б) — то же самое, но скрытое; вариант (в) — каноничный подход, согласованный с правилом feedback_no_destruction (зафиксировано в memory). Старые документы остаются доступны для исторической справки, но не конкурируют с актуальным source of truth.

Тезис 4. Каждое архитектурное решение тезисно обосновано.

Альтернативы: (а) решения фиксируются как fait accompli без обоснования; (б) обоснования в отдельной системе (ADR — Architecture Decision Records); (в) тезисное обоснование внутри документа решения.

Trade-off: вариант (а) приводит к ситуации «не помним, почему сделали так» через 6 месяцев; вариант (б) — стандартная практика (Atlassian, ThoughtWorks), но создаёт второй документ для каждого решения и приводит к рассинхронизации; вариант (в) — обоснование живёт рядом с решением, в одном документе, с альтернативами и trade-off, согласовано с правилом feedback_thesis_based_justification. Это масштабируется без отдельной ADR-системы.

Тезис 5. DocMap MCP — обязательный инструмент работы с документами.

Альтернативы: (а) прямое редактирование .md файлов через текстовые редакторы; (б) Git-based workflow без MCP; (в) DocMap MCP как обязательный инструмент с auto-индексацией.

Trade-off: вариант (а) ломает индекс search'а, не отслеживает связи, не валидирует MDX; вариант (б) — Git fine, но без MCP теряется reactive indexing и валидация; вариант (в) — каноничный подход с tools: docs_index, docs_search, docs_get_section, docs_links, docs_lint, docs_create_file, docs_patch_section, docs_create_section, docs_rename_file, docs_delete_file, docs_delete_section. Это масштабируемое решение для платформы с десятками документов и сложным link graph.

Главные принципы documentation governance​

Принцип 1. Living documentation (живая документация)​

Документация обновляется вместе с платформой, не постфактум. Особенно критично для:

  • domain model (изменения в каноничных сущностях);
  • contracts (OpenAPI / AsyncAPI / Surface contracts);
  • migrations (schema changes);
  • settlement (financial flows);
  • observability (SLI metrics, dashboards);
  • supplier onboarding (правила приёма новых поставщиков);
  • operator playbooks (runbooks, on-call procedures).

Правило: изменение в коде/конфигурации, затрагивающее любой из этих 7 контуров, требует обновления соответствующего документа в той же PR / commit / задаче.

Принцип 2. Single source of truth per domain​

Каждый домен имеет один canonical document в reference/. Документы в overview/ дают высокоуровневую карту, документы в operations/ описывают эксплуатацию, документы в development/ фиксируют процессы, но доменная истина живёт в одном месте.

Правило: при появлении противоречия между двумя документами — определить, какой из них canonical, исправить расхождение в неканоничном.

Документы связаны через wiki-links и Markdown-ссылки. Граф связей должен быть целостным: каждая ссылка резолвится, каждый важный документ имеет backlinks, нет «висящих» документов.

Правило: после каждой материальной правки — docs_links(section_id) для проверки, docs_lint для поиска plain-text refs.

Принцип 4. Truth boundaries first-class​

Каждый документ явно различает уровни истины:

  • canonical (каноничная архитектурная модель);
  • supplier (внешняя реальность поставщиков);
  • operational (текущее состояние эксплуатации);
  • transactional (финансовые и бронирующие транзакции);
  • governance (управленческие решения);
  • analytical (аналитические проекции).

Правило: утверждения в документе должны явно указывать, к какому уровню истины они относятся.

Принцип 5. No destruction (запрет уничтожения)​

Старые документы переименовываются в *-old-YYYY-MM-DD.md со статусом Черновик (правило feedback_no_destruction зафиксировано в memory). Никогда:

  • не удаляем содержимое документа;
  • не перезаписываем без архивации старой версии;
  • не правим текст архивного документа.

Правило: при материальном переписывании документа — docs_rename_file старого в *-old-YYYY-MM-DD.md, потом docs_patch_section шапки старого документа со статусом Черновик (архивный) и пояснением, какой документ заменил, потом docs_create_file нового.

Принцип 6. Тезисное обоснование​

Каждое нетривиальное архитектурное решение в документе тезисно обосновано: альтернативы, trade-off, выбор. См. feedback_thesis_based_justification.

Правило: документ с архитектурным решением без секции «Тезисное обоснование» не считается готовым к utверждению.

Принцип 7. MDX-safe writing​

DocMap рендерится через Docusaurus + MDX. Два класса MDX-ловушек ломают сборку:

  • Класс 1: голый < перед буквой/цифрой → JSX-тег;
  • Класс 2: фигурные скобки {...} в plain-тексте → JSX-выражение.

Правило: перед каждым docs_create_file / docs_patch_section — проверка через grep -nE '<[0-9]' и grep -nE '\{'. Все совпадения в plain-тексте — переоформить (HTML-entity, fenced code block). Полная политика — reference_mdx_safe_writing в memory.

Принцип 8. Language rules — только русский​

Все новые и обновляемые документы пишутся только на русском языке в человеко-читаемом формате. Не смешивать языки в одном предложении. Устоявшиеся англоязычные термины — обязательно с расшифровкой в скобках (например, «коммерческая фиксация (Quote)»). Имена сущностей в коде/JSON/YAML — на английском.

Полная политика — feedback_language_rules в memory.

Жизненный цикл документа​

Документ проходит каноничный жизненный цикл из 5 фаз.

Фаза 1. Создание (creation)​

Триггер: появление архитектурной развилки, нового домена, обнаружение пробела в документации, требование compliance.

Действия:

  1. Sprint context — docs_search(тема) для понимания, что уже есть рядом;
  2. Read neighbours — docs_get_section для каждого соседнего документа, чтение в активный контекст;
  3. Verify implementation — Read/Grep по реальному коду (home-to-go-api, актуальная DDL, конфигурации) для проверки, что задумываемое не противоречит реальности;
  4. Структура документа — определить разделы:
    • шапка (Версия / Дата / Статус);
    • Назначение документа;
    • Тезисное обоснование (если архитектурное решение);
    • Каноничная модель (сущности, связи);
    • Процессы / процедуры;
    • События / интеграции;
    • Открытые вопросы;
    • Связанная документация;
  5. Создание — docs_create_file(file, content) с полной структурой;
  6. MDX-safety — Python-скрипт проверки или grep по двум классам;
  7. Build verify — npm run build (DocMap проекта собирается без ошибок);
  8. Backlinks — обновить «Связанная документация» в соседних документах при необходимости.

Шаблон шапки:

# {заголовок документа}

**Версия:** 1.0
**Дата:** ДД.ММ.ГГГГ
**Статус:** Черновик / Готов к обсуждению / Утверждён

Каноничные статусы:

  • Черновик — документ в работе, не готов к использованию;
  • Готов к обсуждению — документ готов, ожидает review/feedback;
  • Утверждён — документ принят как source of truth (только после явного подтверждения главным архитектором или владельцем домена).

Фаза 2. Review​

Триггер: документ создан со статусом Готов к обсуждению.

Участники review:

  • Domain owner — отвечает за корректность доменной модели;
  • Главный архитектор — отвечает за соответствие правилу 00000 и архитектурной оси;
  • Operations lead — отвечает за реалистичность операционных требований;
  • Compliance officer (для documents с регуляторным impact) — отвечает за GDPR / PSD2 / TOMS / Package Travel Directive соответствие;
  • Stakeholders соседних доменов — отвечают за непротиворечивость со смежными документами.

Процесс review:

  1. Reviewer читает документ через docs_get_section;
  2. Reviewer проверяет соседние документы через docs_links;
  3. Reviewer фиксирует комментарии (через систему трекинга задач или прямо в документе как inline TODO);
  4. Author обрабатывает комментарии, делает обновления через docs_patch_section;
  5. Cycle повторяется до выхода в утверждение или зафиксированных открытых развилок.

Каноничные критерии review (review checklist):

  • ✅ Шапка с Версия / Дата / Статус;
  • ✅ Тезисное обоснование (для документов с архитектурными решениями);
  • ✅ Связь с правилом 00000 и архитектурной осью;
  • ✅ Связь с реальной реализацией (home-to-go-api);
  • ✅ MDX-safe (нет нарушений Класса 1 и Класса 2);
  • ✅ Только русский язык, не смешано с английским в одном предложении;
  • ✅ Английские термины с расшифровкой в скобках при первом упоминании;
  • ✅ Связанная документация — секция в конце с ссылками на все релевантные документы;
  • ✅ Открытые вопросы — фиксированы в отдельной секции, не размыты в тексте;
  • ✅ docs_links показывает целостный link graph;
  • ✅ npm run build проходит без ошибок.

Фаза 3. Утверждение (approval)​

Триггер: review завершён, все материальные комментарии обработаны.

Действия:

  1. Главный архитектор (или domain owner для специализированного документа) явно утверждает документ;
  2. Author обновляет статус в шапке через docs_patch_section: Готов к обсуждению → Утверждён;
  3. Author поднимает версию (например, 1.0 остаётся; следующее материальное обновление будет 1.1 или 2.0);
  4. Author обновляет дату на дату утверждения;
  5. git commit со ссылкой на review.

Правило: статус Утверждён ставится только после явного подтверждения. Author не может ставить Утверждён сам.

Фаза 4. Maintenance (поддержка)​

Триггер: изменение в коде/конфигурации/процессах, затрагивающее документ, или появление нового связанного документа.

Семантическое версионирование документов:

  • Patch (1.0 → 1.0.1) — мелкая правка (опечатки, уточнения, дополнения ссылок);
  • Minor (1.0 → 1.1) — добавление нового материала без изменения уже зафиксированных решений;
  • Major (1.0 → 2.0) — материальное изменение зафиксированных решений (требует архивации старой версии).

Правило для major changes: архивация через *-old-YYYY-MM-DD.md (см. Принцип 5 No destruction). Для minor и patch — docs_patch_section с обновлением Версии и Даты в шапке.

Когда обновлять документ:

  • изменение в коде/конфигурации, затрагивающее доменную модель;
  • изменение API контракта;
  • появление нового релевантного документа, требующее backlink;
  • завершение архитектурной развилки, ранее зафиксированной как «открытый вопрос»;
  • регуляторное изменение (новые требования GDPR, PSD2);
  • post-mortem инцидента, требующий уточнения runbook или SLA.

Фаза 5. Архивация (archival)​

Триггер: документ материально устарел и заменён новой версией, или зафиксированный домен расформирован.

Действия:

  1. docs_rename_file(old, old-YYYY-MM-DD.md) — переименование старого файла с датой архивации;
  2. docs_patch_section шапки — обновить:
    • **Версия:** N.N (архивная);
    • **Дата архивации:** ДД.ММ.ГГГГ;
    • **Статус:** Черновик (архивный, не source of truth);
    • блок-цитата с пояснением, какой документ заменил, и ссылкой на актуальный;
  3. Содержимое архивного документа НЕ правится (исторические формулировки сохраняются);
  4. Если есть актуальный документ-заменитель — обновить его «Связанная документация» с ссылкой на архивный;
  5. docs_lint для проверки, что нет broken links на старое имя;
  6. Update backlinks в documents, которые ссылались на старый file.

Правило: не удаляем *-old-YYYY-MM-DD.md файлы из репозитория. Они часть аудитного следа.

Роли и зоны ответственности​

Главный архитектор (chief architect)​

Ответственность:

  • зафиксировать каноничную архитектурную ось;
  • утверждать документы, влияющие на core domain model;
  • эскалация развилок, требующих стратегических решений;
  • блокировать изменения, нарушающие правило 00000.

Документы под прямой ответственностью:

  • overview/index.md;
  • overview/architectural-anchor-and-business-model.md;
  • overview/operational-spine.md;
  • reference/domain-model.md;
  • development/roadmap.md;
  • архитектурные правила (development/Закон 00000…, Современные лучшие практики…, и т.д.).

Domain owner​

Ответственность:

  • поддерживать canonical document своего домена;
  • обновлять при изменениях в коде/процессах;
  • координировать с владельцами смежных доменов;
  • утверждать review changes для своего домена.

Каноничные domain owners (по доменам):

ДоменDocument(s)Owner role
Платежиpayment-domain.mdFinance Lead / Payment Architect
Бронированиеbooking-state-machine.md, post-booking-lifecycle.mdBooking Domain Lead
Tour Buildertour-builder-domain.md, tour-builder-operational-model.mdTour Builder Product Lead
Tenancytenancy-and-identity.md, multi-tenant-isolation-strength.mdPlatform Lead
Поискsearch-and-discovery.mdSearch Engineering Lead
Поставщикиsuppliers.md, ingestion.mdIntegration Lead
Платёжные взаиморасчётыpartner-finance-and-clearing.md, commercial-model.mdFinance Lead
Уведомленияnotification-and-communication.mdCommunications Lead
Медиа и контентmedia-and-content.mdContent Lead
i18ninternationalization-and-localization.mdi18n Lead
Аналитикаanalytics-and-bi.mdAnalytics Lead
MLml-platform.mdML Engineering Lead
A/Bab-testing-platform.mdExperimentation Lead
Data Platformdata-platform-and-events-tracking.mdData Engineering Lead
API as Productapi-as-product.md, api-metering-and-usage-governance.mdPlatform Product Lead
Tour Builder Operationstour-builder-operational-model.mdTour Builder Engineering Lead

Operations lead​

Ответственность:

  • поддерживать operations-документы;
  • обновлять runbooks, SLA, DR процедуры;
  • координировать with on-call team при изменениях operational processes.

Документы:

  • operations/runbooks-incident-playbooks.md;
  • operations/sla-and-on-call-model.md;
  • operations/disaster-recovery-and-capacity.md;
  • operations/scaling-and-packaging-roadmap.md;
  • operations/deployment.md;
  • operations/observability-and-incident-response.md;
  • operations/release-engineering-and-migrations.md;
  • operations/settlement-and-reconciliation.md.

Technical writer (фаза 5+ development roadmap)​

Ответственность (когда роль появится):

  • редактирование документов на ясность и согласованность;
  • проверка соответствия language rules;
  • координация cross-domain документов;
  • поддержка glossary и инфраструктуры документации;
  • onboarding новых членов команды в документную работу.

На стадиях 0–4 эта роль не выделена. Авторы документов сами проверяют ясность.

Compliance officer (фаза 4+ development roadmap)​

Ответственность:

  • проверка документов на соответствие GDPR / PSD2 / TOMS / Package Travel Directive;
  • audit trail для регуляторно-чувствительных решений;
  • сопровождение SOC 2 / ISO 27001 audit с использованием документов как evidence.

DocMap MCP — каноничные процедуры​

Перед каждой материальной правкой​

Каноничный pre-flight протокол:

  1. docs_index — общая карта проекта (если давно не делали);
  2. docs_search(тема) — найти соседей;
  3. docs_get_section(...) для каждого соседа — прочитать в активный контекст;
  4. Read/Grep реальный код — сверить с реализацией;
  5. Проверить с уже зафиксированными стратегическими решениями (memory, CLAUDE.md);
  6. Только после полного контекста — правка через docs_patch_section или docs_create_file.

При создании нового документа​

mcp__docmap-mcp__docs_create_file(
  project="vitiana-api-platform",
  file="reference/новый-документ.md",
  content="# Заголовок\n\n**Версия:** 1.0\n**Дата:** ..."
)

После создания:

  • проверка MDX-safety;
  • npm run build верификация;
  • update backlinks в соседних документах через docs_patch_section;
  • запуск tools/build_project_index.sh vitiana-api-platform (напоминание пользователю).

При обновлении секции​

mcp__docmap-mcp__docs_patch_section(
  section_id="vitiana-api-platform::file.md::heading-slug",
  new_body="новый текст body, без heading line"
)

patch_section не трогает heading line — только тело секции.

При архивации файла​

mcp__docmap-mcp__docs_rename_file(
  old_file="reference/имя.md",
  new_file="reference/имя-old-2026-04-27.md"
)

После переименования:

  • docs_patch_section шапки старого файла — обновить статус;
  • docs_lint для поиска broken links на старое имя;
  • update backlinks в documents, которые ссылались.
mcp__docmap-mcp__docs_links(
  section_id="...",
  direction="both"  // forward + backlinks
)
mcp__docmap-mcp__docs_lint(project="vitiana-api-platform")

Структура документа — каноничные секции​

Минимальная структура (для всех документов)​

  1. YAML frontmatter — обязательный блок в самом верху файла (раньше всего остального содержимого):

    ---
    title: "Название документа на русском"
    draft: false
    ---

    Зачем. Каталогизация документов через CMS (Decap CMS) настроена на коллекцию с format: frontmatter и обязательными полями title (заголовок) и draft (флаг черновика). Без этого блока CMS просто не видит документ — он не появляется в списке для редакторов. Docusaurus продолжает рендерить документ (использует первый # H1 как fallback-title), поэтому проблема незаметна на сайте, но обнаруживается при попытке отредактировать документ через CMS.

    Когда draft: true. Документ виден в CMS, но не публикуется на сайте. Используется для документов в активной разработке, которые нельзя ещё показывать читателям. Финальные документы — draft: false.

    Важно. Инструмент docs_create_file из DocMap MCP не добавляет frontmatter автоматически. При создании любого нового документа автор обязан включить блок frontmatter в content. Это правило обязательно для всех документов проектов, индексируемых CMS.

  2. H1 заголовок (на русском, с пояснением английского термина в скобках при необходимости);

  3. Шапка (Версия / Дата / Статус) сразу после H1;

  4. Назначение документа — что фиксирует, для кого, какую развилку закрывает;

  5. Тезисное обоснование (для документов с архитектурными решениями) — 3–7 тезисов с альтернативами и trade-off;

  6. Тело документа — каноничные сущности, процессы, правила;

  7. Открытые вопросы — развилки, требующие решения (не должны размываться в тексте);

  8. Связанная документация — ссылки на все релевантные документы.

Расширенная структура (для domain documents)​

Дополнительно:

  • Каноничная модель — сущности, атрибуты, связи;
  • Процессы / процедуры — пошаговые алгоритмы;
  • Каноничные события — events, публикуемые в общую шину;
  • Технологические выборы — таблица «по фазам» (если применимо);
  • Связь с другими доменами — явное описание интеграционных границ.

Расширенная структура (для operations documents)​

Дополнительно:

  • Целевые показатели — SLI, RTO/RPO, capacity targets;
  • Процедуры эскалации — кто что делает в каких случаях;
  • Связь с runbooks / SLA / DR / capacity — четыре столпа.

Расширенная структура (для development documents)​

Дополнительно:

  • Главный принцип — общая логика (как главный принцип развития в roadmap);
  • Стадии / фазы — если документ описывает roadmap или maturity model;
  • Сквозные workstreams — если применимо.

Структура каталога DocMap​

docs/vitiana-api-platform/
├── _project_.json
├── index.md                    # auto-generated через build_project_index.sh
├── overview/
│   ├── _category_.json
│   ├── index.md
│   ├── architectural-anchor-and-business-model.md
│   ├── operational-spine.md
│   ├── relation-to-implementation-baseline.md
│   └── layers.md
├── reference/                  # каноничная доменная и платформенная модель
│   ├── _category_.json
│   ├── domain-model.md
│   ├── tenancy-and-identity.md
│   └── ...
├── operations/                 # эксплуатация
│   ├── _category_.json
│   ├── deployment.md
│   ├── runbooks-incident-playbooks.md
│   ├── sla-and-on-call-model.md
│   └── ...
├── development/                # процессы разработки и governance
│   ├── _category_.json
│   ├── roadmap.md
│   ├── documentation-governance.md
│   ├── team-and-staffing-plan.md
│   └── ...
└── assets/                     # медиа-файлы

Правила структуры:

  • новые документы — только в одной из 4 папок (overview/, reference/, operations/, development/), не в корне;
  • архитектурные правила (Закон 00000…, Современные лучшие практики…) — в development/;
  • архивные *-old-YYYY-MM-DD.md — в той же папке, что и актуальный документ;
  • assets/ — только медиа (картинки, диаграммы), не markdown.

Обновление index.md​

index.md каждого проекта — auto-generated, не редактируется вручную. Обновляется через:

tools/build_project_index.sh vitiana-api-platform

Триггер запуска: после создания/переименования/удаления любого .md файла в проекте.

Каноничные события documentation governance​

События для отслеживания documentation health:

  • doc.created — новый документ создан;
  • doc.published — статус → Утверждён;
  • doc.updated.major — major version bump;
  • doc.updated.minor — minor version bump;
  • doc.archived — архивация;
  • doc.review.requested — запрошен review;
  • doc.review.completed — review завершён;
  • doc.lint.broken_link_detected — broken link;
  • doc.lint.mdx_violation_detected — MDX violation.

Эти события публикуются в общий event stream (см. data-platform-and-events-tracking.md) и используются для дашбордов documentation health.

Метрики качества документного слоя​

Метрики покрытия (coverage)​

  • Каноничный domain coverage — процент доменов с актуальным canonical document (target: 100%);
  • Operations coverage — процент operational процедур, описанных в runbook (target: 100%);
  • Test coverage of architectural decisions — процент архитектурных решений с тезисным обоснованием (target: 100%).

Метрики свежести (freshness)​

  • Median document age — медиана возраста документов с момента последнего material update (target: ≤ 90 дней для активных доменов);
  • Stale documents — количество документов без обновлений более 180 дней (target: 0 для production-critical документов).

Метрики целостности (integrity)​

  • Broken links — количество broken links по результату docs_lint (target: 0);
  • MDX violations — количество MDX violations (target: 0);
  • Backlink completeness — процент документов с обратными ссылками от соседних (target: ≥ 95%);
  • Build success rate — процент npm run build успешных запусков (target: 100%).

Метрики использования (engagement)​

(применимы с фазы 4 development roadmap, когда DocMap опубликована публично):

  • Page views на canonical documents;
  • Time on page (медиана);
  • Search queries без результатов — индикатор пробелов в документации;
  • Partner support tickets, ссылающиеся на документацию — индикатор ясности.

Процесс архитектурного review​

Каноничные триггеры review​

  1. Новое решение — создан документ с архитектурным решением;
  2. Cross-domain change — изменение, влияющее на несколько доменов;
  3. Material schema change — изменение каноничной сущности или её атрибутов;
  4. API contract change — изменение OpenAPI / AsyncAPI;
  5. Compliance impact — изменение, влияющее на регуляторное соответствие;
  6. Operational impact — изменение, влияющее на SLI / SLA / runbook / DR.

Процесс review​

  1. Request — author явно запрашивает review через issue tracker (ссылка на документ);
  2. Reviewer assignment — domain owner соседних доменов + главный архитектор + (опционально) operations lead, compliance officer;
  3. Review meeting — не обязательно, но рекомендуется для cross-domain changes (синхронный, 30–60 минут);
  4. Comments — reviewers фиксируют комментарии в issue tracker или прямо в документе;
  5. Iteration — author обрабатывает комментарии через docs_patch_section, отвечает в issue tracker;
  6. Approval — каждый reviewer явно даёт ✅ или ❌ с комментарием;
  7. Resolution — все ❌ обработаны (или зафиксированы как открытые развилки), все ✅ получены → status Утверждён.

Эскалация при разногласиях​

При неразрешимом разногласии между reviewers:

  1. Тезисное обоснование — author явно фиксирует альтернативы и trade-off в документе;
  2. Рекомендация главного архитектора — арбитраж от главного архитектора;
  3. Strategic decision — если развилка стратегическая (не тактическая), эскалация в product owner / CTO;
  4. Открытая развилка — если решение не может быть принято сейчас, фиксируется в секции «Открытые вопросы» документа с явным указанием, что блокирует.

Документы с особым регламентом​

Несколько документов имеют усиленный governance из-за их центральной роли:

Канонические документы (требуют согласия главного архитектора + 2 domain owners)​

  • overview/index.md — главная архитектурная карта;
  • overview/architectural-anchor-and-business-model.md — бизнес-якорь;
  • overview/operational-spine.md — операционная ось;
  • reference/domain-model.md — каноничная доменная модель;
  • reference/tenancy-and-identity.md — модель tenancy;
  • reference/commercial-model.md — коммерческая модель;
  • reference/api-contracts.md — surface contracts;
  • архитектурные правила в development/ (Закон 00000, Современные лучшие практики, Развитие без деградации, Тезисное обоснование, Эластичное масштабирование).

Регулируемые документы (требуют согласия compliance officer с фазы 4)​

  • reference/payment-domain.md (PSD2 SCA);
  • reference/multi-tenant-isolation-strength.md (data residency, GDPR);
  • reference/internationalization-and-localization.md (regulatory text translations);
  • reference/data-platform-and-events-tracking.md (GDPR data processing);
  • reference/analytics-and-bi.md (k-anonymization для regulatory exports);
  • reference/notification-and-communication.md (consent, GDPR);
  • operations/disaster-recovery-and-capacity.md (SOC 2 audit evidence);
  • operations/sla-and-on-call-model.md (commercial SLA, regulatory uptime requirements).

Operational-critical документы (требуют согласия operations lead)​

  • все документы в operations/ за исключением архивных.

Onboarding новых участников документной работы​

Чтение в установленном порядке​

  1. CLAUDE.md (или эквивалент в development/) — общие правила работы;
  2. overview/index.md — архитектурная карта;
  3. overview/architectural-anchor-and-business-model.md — бизнес-якорь;
  4. development/roadmap.md — стадии развития;
  5. development/documentation-governance.md (этот документ) — процессы;
  6. Архитектурные правила в development/ (особенно правило 00000).

Каноничный first contribution​

Новый участник делает first contribution следуя протоколу:

  1. Выбирает документ для правки (минимальный — typo fix, средний — добавление backlinks, большой — новая секция);
  2. Запускает локально npm run build для baseline;
  3. Использует docs_patch_section (не Edit/Write) для правки;
  4. Проверяет MDX-safety;
  5. npm run build после правки → должен пройти;
  6. Запрашивает review.

Связь с другими governance процессами​

Connection to release engineering​

Изменение API контракта обязательно сопровождается обновлением:

  • reference/api-contracts.md;
  • OpenAPI / AsyncAPI skeletons (development/openapi-skeletons-and-resource-families.md, asyncapi-skeletons-and-event-envelopes.md);
  • compatibility checklist (development/consumer-compatibility-checklist-by-release-unit.md);
  • version evolution policy (development/version-evolution-policy-for-async-event-contracts.md).

См. release-engineering-and-migrations.md.

Connection to incident management​

Post-mortem каждого major incident обязательно сопровождается:

  • обновлением соответствующего runbook (operations/runbooks-incident-playbooks.md);
  • если выявлен SLI/SLA gap — обновлением operations/sla-and-on-call-model.md;
  • если выявлена DR gap — обновлением operations/disaster-recovery-and-capacity.md.

Connection to compliance audit​

Аудиты SOC 2 / ISO 27001 / GDPR требуют document version history. DocMap архивные документы (*-old-YYYY-MM-DD.md) — основной evidence для:

  • архитектурных решений (тезисное обоснование как ADR-эквивалент);
  • governance процессов (этот документ);
  • operational maturity (runbooks, SLA reports, DR drills);
  • security posture (multi-tenant-isolation-strength, payment-domain).

Открытые вопросы и развилки​

  1. Документы на двух языках для регулируемых юрисдикций. Должны ли regulated документы (PSD2, GDPR) существовать также на английском для аудиторов? Решение — на стадии 4, при первом подготовительном аудите SOC 2.
  2. ADR (Architecture Decision Records) как отдельный формат. Текущая модель — тезисное обоснование внутри документа решения. Альтернатива — отдельные ADR-документы. Решение по результатам стадии 2 (при росте числа архитектурных решений может потребоваться отдельный формат).
  3. Public DocMap publication. Когда публиковать DocMap наружу как часть partner experience? Решение — на стадии 3 (controlled external beta).
  4. Документация для open source компонентов. Если платформа выделит компоненты в open source — они получают отдельный governance? Решение — после стадии 5.
  5. AI-assisted documentation review. Можно ли использовать LLM для предварительного review документов? Кто несёт ответственность за финальное одобрение? Решение — экспериментально на стадии 2, evaluation на стадии 3.

Каноничный итог​

Documentation governance для платформы Vitiana — first-class дисциплина с:

  • 8 главными принципами (living documentation, single source of truth, link integrity, truth boundaries, no destruction, тезисное обоснование, MDX-safety, language rules);
  • 5-фазным жизненным циклом документа (creation → review → approval → maintenance → archival);
  • явными ролями (главный архитектор, domain owners, operations lead, technical writer, compliance officer);
  • каноничными процедурами DocMap MCP;
  • структурными требованиями к каждому типу документа;
  • метриками качества документного слоя.

Без этой дисциплины документный слой превращается либо в фрагментированный набор устаревших файлов, либо в bottleneck централизованной writer-команды. Вариант по этому документу — масштабируемая модель платформы верхнего уровня.

Связанная документация​

Архитектурная основа​

Документы развития​

Архитектурные правила​

Операционные документы​

Платформенные домены​