Qadam Roadmap
← Назад к библиотеке
проектdocs/governance/documentation-standard.md

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

Обновлён 1 апр. 2026 г., 12:41 · 0 комментариев

ИсходникСкачать

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

Паспорт документа

  • Статус документа: living standard
  • Актуально на: 29 марта 2026 года
  • Владелец: backend/platform-команда
  • Пересмотр: при изменении правил разработки, ownership-модели или документационного процесса
  • Область применения: нормативный слой инженерных и документационных правил проекта
  • Связанные документы:

Цель документа

Этот документ фиксирует единый стандарт оформления и сопровождения документации Qadam. Его задача — сделать документальный слой:

  • передаваемым;
  • машиночитаемо-предсказуемым;
  • единообразным для новой команды;
  • устойчивым к drift между кодом, production и markdown-слоем.

1. Где стандарт обязателен

Стандарт обязателен для:

  • всех канонических документов в qadam-core/docs;
  • платформенных документов в qadam-core/specs/qadam-platform;
  • локальных handoff-документов в qadam-web/docs, если они используются как рабочий onboarding/reference слой;
  • новых документов, которые претендуют на роль источника истины.

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

  • архив plans/, если это исторические снимки;
  • временные черновики вне канонического слоя;
  • autogenerated файлы, если они не выступают как human source of truth.

2. Обязательная структура документа

Каждый канонический документ должен иметь:

  1. Заголовок первого уровня #.
  2. Сразу после него раздел ## Паспорт документа.
  3. Внутри паспорта фиксированный набор полей.

Обязательные поля паспорта:

  • Статус документа
  • Актуально на
  • Владелец
  • Пересмотр
  • Область применения
  • Связанные документы

Допустимо:

  • добавлять короткое вводное описание после паспорта;
  • сохранять YAML frontmatter в docs/Agents/rules/*, если он уже используется как служебный слой;
  • для компактных rule/reference-card документов в docs/Agents/rules/* оставлять passport сразу после frontmatter, даже если отдельный #-заголовок в файле не используется;
  • оставлять внутренние статусные разделы внутри документа, если они описывают статус системы, а не статус самого документа.

Недопустимо:

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

3. Канонические значения статуса документа

Используются следующие значения:

  • living document — живой документ, который регулярно обновляется по мере развития системы;
  • living standard — живой нормативный документ или правило;
  • working reference — рабочая справка для ежедневного использования;
  • working spec — рабочая проектная спецификация, связанная с реализацией;
  • target requirements — документ целевых требований;
  • historical snapshot — исторический снимок или audit фиксированного момента времени;
  • local handoff copy — локальная копия канонического документа в другом репозитории;
  • compatibility pointer — совместимый указатель на канонический документ.

Если документ не вписывается в эти значения, нужно осознанно выбрать ближайший класс, а не придумывать произвольный статус.

4. Правила заполнения полей паспорта

Статус документа

Показывает lifecycle самого markdown-файла, а не статус фичи или проекта.

Актуально на

  • указывается в явной форме: 28 марта 2026 года;
  • обновляется при содержательной ревизии документа;
  • не должна быть старше фактического последнего крупного изменения документационного контекста.

Владелец

Это роль, ответственная за актуальность документа, а не обязательно конкретный человек.

Примеры:

  • backend/platform-команда
  • frontend-команда
  • backend/platform-команда, совместно с frontend-командой

Пересмотр

Это не “когда-нибудь”, а явный триггер пересмотра.

Хорошие примеры:

  • при изменении production runtime, доменов или systemd/nginx-контура
  • при изменении API-контракта или auth-flow
  • при изменении roadmap, процессов разработки или ownership-модели

Область применения

Коротко фиксирует, где документ считается применимым и для какого слоя он является источником истины.

Связанные документы

Минимум 2-3 ссылки на реально связанные source-of-truth документы, а не случайный список “что ещё существует”.

5. Языковые правила

  • канонический слой ведётся на русском языке;
  • английский допустим только для терминов, названий технологий, API, кода и устоявшихся обозначений;
  • смешанные русско-английские заголовки допускаются только если английская часть является названием технологии или технического артефакта;
  • английский prose не должен быть основным языком канонического документа.

6. Правила индексации и навигации

  • новый канонический документ должен быть добавлен в README.md, если он становится source of truth;
  • связанные документы должны быть перелинкованы относительными markdown-ссылками;
  • изменение пути канонического документа считается завершённым только после починки всех внутренних ссылок;
  • документ, который не должен участвовать в основной навигации, должен быть либо архивным, либо явно помеченным historical/reference-слоем.

7. Правила сопровождения

Документ должен обновляться в том же change package, если изменение затрагивает его область.

Обязательно синхронно обновлять:

  • project/current-state.md — при изменении реального runtime и production;
  • project/roadmap.md — при изменении очередности крупных пакетов;
  • project/requirements.md — при изменении бизнес- или инженерных требований;
  • project/execution-checkpoints.md — при изменении статуса этапа или checkpoint;
  • project/project-change-log.md — для каждого завершённого change package;
  • operations/deployment-runbook.md — при изменении deploy/rollback/ops модели;
  • operations/environment-matrix.md — при изменении env или access boundaries;
  • architecture/api-routes.md и OpenAPI — при изменении API-контракта;
  • frontend/frontend-change-log.md — при frontend-значимом API change;
  • specs/qadam-platform/* — при изменении платформенных решений.

8. Минимальный quality gate для документации

Канонический docs-layer считается в порядке только если:

  1. У документов есть паспорт.
  2. Относительные markdown-ссылки не биты.
  3. Нет ложных source-of-truth документов в legacy-папках.
  4. Новый канонический документ отражён в индексе.
  5. Документы не расходятся с текущим runtime, контрактами и roadmap.

Базовая исполнимая команда для этого gate в qadam-core:

pnpm check:docs

9. Шаблон

# Название документа

## Паспорт документа

- Статус документа: living document
- Актуально на: 28 марта 2026 года
- Владелец: backend/platform-команда
- Пересмотр: при изменении <триггеров>
- Область применения: <какой слой и где документ считается source of truth>
- Связанные документы:
  - [Документ 1](<относительный-путь-к-документу-1>)
  - [Документ 2](<относительный-путь-к-документу-2>)
  - [Документ 3](<относительный-путь-к-документу-3>)

10. Практическое правило

Если новый документ невозможно быстро классифицировать по этому стандарту, это обычно означает одно из двух:

  1. документ не канонический и не должен лежать в docs/;
  2. у команды ещё неясно, зачем этот документ нужен и кто им владеет.

В обоих случаях сначала нужно прояснить роль документа, а уже потом добавлять его в канонический слой.