Docs-as-code — документація в тому самому change set
Docs-as-code означає, що технічна документація живе в репозиторії, потрапляє до diff, проходить review і перевіряється разом із кодом. Документ не є довідкою «десь поруч»: він описує конкретну поведінку, команди або процедуру.
Зміна коду та застаріла інструкція утворюють неповний delivery. Тому документацію потрібно оновлювати в тому самому PR, коли змінюється її джерело правди.
| Артефакт | Типовий зміст |
|---|---|
| README | Setup, основні команди та змінні середовища |
| API documentation | Маршрути, методи, запити, відповіді та контракти |
| Runbook | Діагностика, реагування на інцидент і відновлення |
| Onboarding guide | Підготовка чистого робочого середовища |
| Changelog / release notes | Підтверджені зміни між версіями |
Джерело істини важливіше за памʼять
- звіряйте API-опис із controller, DTO та тестами;
- перевіряйте команди через package scripts, Gradle tasks або реальний запуск;
- порівнюйте env у README, .env.example, Compose та конфігурації застосунку;
- підтверджуйте runbook логами, alert-ами й фактичним smoke-сценарієм;
- позначайте неперевірені твердження як unknown, а не подавайте їх упевнено.
Claude як перевіряльник документації
- Передайте Claude конкретний документ і перелік файлів-джерел.
- Попросіть знайти розбіжності в командах, route, env або прикладах.
- Вимагайте посилання на файл, рядок або тест для кожного зауваження.
- Окремо попросіть перелік непідтверджених тверджень.
- Підготуйте малий diff і перевірте його практичним запуском.
Input: README.md and the referenced setup files
Check: commands, ports, env names, API routes and examples
Return: mismatches with evidence and suggested minimal edits
Do not invent endpoints, variables or recovery commands
Do not edit files before the report is reviewedGenerated text не дорівнює актуальній документації
Генерація може створити читабельний текст, але delivery-документація повинна бути перевірюваною. Важливо не те, наскільки переконливо звучить опис, а чи запускається команда, чи збігається маршрут із кодом і чи відповідає приклад фактичному DTO.
Наприклад, якщо API почало повертати approvalRequired: true зі статусом PENDING_APPROVAL, runbook має пояснювати очікування ручного підтвердження, а не радити повторювати запит навмання.
| Перевірка | Доказ |
|---|---|
| Команда | Фактичний запуск на чистому або описаному середовищі |
| API route | Controller, route test або контрактний тест |
| Приклад відповіді | DTO, serializer і тестовий результат |
| Runbook | Лог, smoke-check або перевірений recovery path |
Docs gate перед merge
- після зміни setup оновлено README та onboarding;
- після зміни route або response оновлено API-опис;
- приклади команд і запитів перевірені практично;
- документація не містить секретів або приватних значень;
- бізнесові компроміси й висновки ADR залишилися під людським review.
Канонічне джерело уроку · JavaRush
Відкрити матеріал JavaRush