dzentra_bot/docs/market_intelligence/decisions/decision-007-documentation-is-code.md

Decision 007 — Documentation Is Code

Статус

Accepted

---

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

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

---

Контекст

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

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

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

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

---

Проблема

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

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

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

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

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

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

---

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

Вариант 1

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

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

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

Недостатки

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

---

Вариант 2

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

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

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

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

Недостатки

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

---

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

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

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

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

---

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

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

Например:

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

---

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

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

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	Первое принятие архитектурного решения.