# Decision 007 — Documentation Is Code

## Статус

**Accepted**

---

# Дата принятия

Принято во время разработки Stage-08.2 **Engine Runtime Contract**.

---

# Контекст

Во время разработки первых компонентов Market Intelligence стало очевидно, что исходный код и документация развиваются одновременно.

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

- архитектурой;
- реализацией;
- инженерными решениями;
- фактическим состоянием проекта.

В результате документация перестаёт отражать реальное устройство системы.

---

# Проблема

Во многих проектах документация рассматривается как дополнительный материал.

Обычно процесс выглядит следующим образом:

```text
Написание кода
        ↓
Код работает
        ↓
Документацию обновим позже
```

На практике "позже" часто не наступает.

Через некоторое время:

- документация устаревает;
- архитектурные решения теряются;
- новые разработчики вынуждены изучать проект только по исходному коду.

---

# Рассмотренные варианты

## Вариант 1

Документация обновляется по мере возможности.

### Преимущества

- меньше работы во время реализации.

### Недостатки

- документация быстро устаревает;
- теряются архитектурные решения;
- сложно понять историю развития проекта.

---

## Вариант 2

Документация обновляется одновременно с кодом.

Build считается завершённым только после обновления всей связанной документации.

### Преимущества

- документация всегда соответствует проекту;
- архитектурные решения сохраняются;
- упрощается сопровождение;
- сохраняется история развития платформы;
- новые разработчики быстрее понимают проект.

### Недостатки

- требуется дополнительное время на оформление документации.

---

# Принятое решение

Документация является частью исходного кода проекта.

Каждый Build считается завершённым только после обновления всей связанной документации.

Документация имеет такую же обязательность, как Compile Check или Architecture Review.

---

# Обязательная документация Build

После завершения каждого Build обязательно обновляются все связанные документы.

Например:

- Build Document;
- Build History;
- Architecture Decisions (при необходимости);
- Runtime Contract (при необходимости);
- Development Process (при необходимости);
- README соответствующего раздела (при необходимости).

---

# Правило завершения Build

Build считается завершённым только после прохождения полного цикла:

```text
Architecture Design
        ↓
Implementation
        ↓
Compile Check
        ↓
Architecture Review
        ↓
Domain Review
        ↓
Documentation Update
        ↓
User Confirmation
        ↓
Build Closed
```

Если документация не обновлена, Build остаётся незавершённым.

---

# Причины принятия решения

Использование данного подхода позволяет:

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

---

# Последствия

После принятия настоящего решения:

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

---

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

- `development_process.md`
- `build_history.md`
- `architecture_principles.md`
- `runtime_contract.md`

---

# История изменений

| Версия | Изменение |
|---------|-----------|
| 1.0 | Первое принятие архитектурного решения. |