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

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

- Статус документа: living standard
- Актуально на: 29 марта 2026 года
- Владелец: backend/platform-команда
- Пересмотр: при изменении правил разработки, ownership-модели или документационного процесса
- Область применения: нормативный слой инженерных и документационных правил проекта
- Связанные документы:
  - [Индекс документации](../README.md)
  - [Roadmap](../project/roadmap.md)
  - [Change package standard](./change-package-standard.md)
  - [Аудит документации](../audits/documentation-audit-2026-03-28.md)

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

Этот документ фиксирует единый стандарт оформления и сопровождения документации 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](../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`:

```bash
pnpm check:docs
```

## 9. Шаблон

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

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

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

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

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

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

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