Рубрика ревʼю docs-as-code

Docs-as-code перевіряє текст як зміну коду

Документаційний diff потрібно перевіряти так само уважно, як код: чи відповідають твердження репозиторію, чи працюють команди, чи немає вигаданих сутностей і чи достатньо джерел для висновків.

Переконливий стиль не є доказом достовірності. Приймається документ, який можна відтворено перевірити.

Рубрика перевірки документа

1. Перегляньте git diff і межі зміни.
2. Знайдіть кожен згаданий файл, клас, маршрут або команду.
3. Перевірте назви через find, grep або IDE.
4. Скопіюйте команди з документа й запустіть їх у правильному каталозі.
5. Видаліть або позначте непідтверджені твердження.
6. Звірте опис ризиків, обмежень і відкритих питань.
7. Повторно перегляньте малий, зрозумілий diff.

find <каталог> -name "<імʼя-файлу>"
grep -R "<назва-сутності>" <каталог>
git diff -- README.md docs/

Доказова перевірка запуску

docker compose up -d db
./gradlew bootRun
cd apps/web && npm run dev

Не змішуйте різні ревʼю в один diff

• не поєднуйте запуск, API, архітектуру й troubleshooting без потреби;
• не дублюйте неперевірені відомості в кількох документах;
• використовуйте API_MAP.md як проміжне джерело для інтеграцій;
• після стабілізації ручних перевірок їх можна оформити як повторюваний workflow.

Критерій готовності документа

Документ готовий тоді, коли його твердження мають джерела, команди перевірені або явно обмежені, вигадані сутності відсутні, а список припущень і обмежень доступний читачеві. Такий docs-as-code підхід робить документацію частиною інженерного процесу, а не декоративним текстом.