Проблема документації — вона швидко старіє
Якщо доки живуть “десь у Google Doc”, їх важко підтримувати синхронно з кодом. Docs‑as‑code вирішує це: документація версіонується, проходить review і деплоїться так само, як продукт.
1) Docs‑as‑code: базовий набір
- README + структура проекту.
- How to run / env / secrets (без самих секретів).
- Опис сервісів і інтеграцій.
2) ADR: фіксуємо архітектурні рішення
Коротко: контекст → рішення → наслідки. ADR зберігає “чому так”, щоб через 6 місяців не було повторних дискусій.
3) RFC: керовані зміни
RFC корисні для великих змін (міграції, модульність, новий білінг): описуємо підхід, ризики, rollout і план відкату.
4) Changelog і runbooks
- Changelog для релізів: що змінили, що впливає на користувачів.
- Runbooks: що робити при інциденті, де дивитися метрики/логи.
Підсумок
Жива документація — це процес: version control, review, короткі формати (ADR/RFC) і орієнтація на практичне використання. Тоді доки реально економлять час.