Інженерна документація з AI: що пише добре, а що ні

Коли VP of engineering у 200-особистій компанії сказав мені, що вони "віддали проблему документації AI", я запитав — якій документації. Команда тихо коммітнулася на AI-згенероване все — API-референси, runbooks, design docs, ADR. Через шість місяців design docs тихо переписали люди, а API-референс був найкращим за всю історію.

Чому AI-документація працює для одних docs і не для інших?

Бо "документація" — це три різні роботи в одному плащі. Reference docs описують, що це за штука. Operational docs описують, як цим користуватися. Decision docs описують, чому штука існує саме так. AI компетентний у перших двох і ненадійний у третьому — і причина структурна, не лімітація моделі.

Definition: Reference doc — документ, чиє джерело правди — код або config (API-сигнатури, env vars, command flags). Оновлюється механічно.

Reference і operational docs виводяться з артефактів, які AI може прочитати. API-сигнатури — у коді. Env vars — у конфіг. Runbook-кроки мапляться на алерти і історію інцидентів. Робота AI — переклад, не винахід. Переклад — там, де AI найсильніший.

Design docs і decision records виводяться з судження, яке AI прочитати не може. Чому команда обрала Postgres замість DynamoDB? Бо двоє інженерів мали операційні шрами від DynamoDB на минулій роботі, CTO зважував надійність вище scale-out, і існуючий observability-тулінг вже мав Postgres-дашборди. Нічого з цього немає в кодбазі.

Що AI пише добре

API-референс

AI генерує точний API-референс з вихідного коду — типи параметрів, return shapes, error codes, базовий приклад використання. Output консистентний між endpoints — те, що люди заледве підтримують, коли reference doc — рукописний sidecar. Цикл підтримки замикається автоматично: код змінюється → doc регенерується.

Setup guide / onboarding doc

AI добре пише setup guides з реальних setup-скриптів, README і deploy-конфіг. Ловить розбіжності між тим, що каже README, і тим, що робить скрипт — це причина №1, чому setup guides застарівають. Onboarding doc першого дня, який AI чернетить з repo + scripts + env-vars — зазвичай 80% коректний у день 1 і покращується з feedback.

Runbook

Runbooks — це operational reference: для alert X роби Y, ескалюй Z. AI добре чернетить це з визначення алерту, архітектури сервісу і історії інцидентів. Працюючий патерн: кожен новий алерт іде з AI-чернеткою runbook-запису, яку on-call інженер редагує в перший тиждень, коли алерт спрацював.

Definition: Runbook — operational doc, що парить алерт або failure mode з діями, які on-call інженер має зробити. Живе чи вмирає на свіжості.

Що AI пише погано

Design doc

Design doc виправдовує неочевидний вибір. AI може описувати опції і trade-offs в абстракції, але не може сказати, який trade-off ця команда має прийняти і чому. Результат — прісний: "Option A має вищу availability, Option B — нижчу вартість." Людський design doc каже: "Ми беремо Option A, бо outage минулого кварталу коштував нам 3 enterprise-renewals, і ми це більше не їмо."

Architecture decision record (ADR)

ADR явно про "чому". AI-згенеровані ADR читаються як Wikipedia-резюме технології. Людські ADR читаються як спогад розмови — і це єдине, для чого ADR існує. Через шість місяців, коли хтось запитає "чому ми це обрали" — відповість тільки людська версія.

Roadmap-adjacent docs

Усе, що каже "що йде і чому" — квартальні інженерні плани, roadmap-формулювання, внутрішнє позиціонування refactor — залежить від контексту поза кодбазою. AI-чернетки тут читаються як generic. Люди пишуть це або це читається як маркетинг.

Поділ — copy/paste матриця

## Поділ AI/людина по docs

| Тип doc            | AI чернетить? | Людина володіє? | Тригер оновлення |
|--------------------|---------------|------------------|------------------|
| API reference      | Так, 100%     | Spot review      | На зміні коду    |
| Setup guide        | Так, 100%     | Редаг. щотижня   | На зміні repo    |
| Runbook запис      | Так, 100%     | On-call редагує  | На зміні алерту  |
| Postmortem timeline| Так, 100%     | RCA секція       | Per інцидент     |
| Design doc         | Outline       | Повне body       | На зміні scope   |
| ADR                | Template      | Повне body       | Per рішення      |
| Quarterly plan     | Ні            | Повне            | Квартально       |
| Onboarding wiki    | Секції        | Org-context      | Щомісяця         |

## Правила оновлення
- AI-чернетки авто-регенеруються на зміні джерела + постять diff PR.
- Human-owned docs мають названого owner з квартальним нагадуванням.
- Mixed docs (outline AI / body human) отримують "last reviewed" stamp.

Матриця — це те, що допомагає поділу пережити квартал. Без неї кожна нова doc стає дебатом, чи має AI її писати.

Tool tip (Course for Business): Причина, чому інженерні doc-rollouts провалюються — не тулінг, а те, що ніхто в команді не знає, де межа AI. Наша 6-тижнева програма використовує рамку Augment, don't replace, щоб провести цю межу явно по типу doc, і AI Champions (1:15-20) роблять так, що інженери знають, які docs вони далі мають писати самі. Тиждень 3 включає Shoulder-to-Shoulder сесію, де сеньйор парується з джуном на переписуванні AI-чернетки runbook — джун вчиться doc-крафту, runbook стає точним. Дивіться програму на https://course.aiadvisoryboard.me/business.

Team scan (що AI champions репортять після тижня 1)

• ~85% інженерів використовували AI для чернетки принаймні однієї doc цього тижня
• Найчастіший перший use case: регенерація stale README або API ref
• Збережений час на doc: 30-90 хвилин на reference docs, ~нуль на design docs
• Топ-скарга: "AI design doc звучав впевнено і був неправильний" — флагуй тип doc, не AI
• Один інженер повністю переписав AI-чернетку ADR — це очікуваний патерн, поділись
• Покриття runbook-ів алертами зросло з ~40% до ~85% за тиждень — найбільша перемога
• Last-updated-stamp API reference перейшов з 6-місячного застою на current
• Нуль design docs зашипилось чисто AI-написаних — це лінія, яку тримаєте
• Один champion провів матрицю поділу на engineering all-hands — приймайте як kickoff-патерн

Micro-case (що змінюється за 7-14 днів)

90-інженерна SaaS-компанія мала три compounding-проблеми документації: API-референс застарів на 6 місяців, runbooks покривали 40% алертів, що пейджать, а папка design docs була повна напівдоробленими чернетками, бо сеньйори не хотіли витрачати день на doc. Розділили роботу за типом у тижні один — AI взяв регенерацію API-ref і runbook на щоденний job, люди тримали design docs і квартальні плани як раніше. До дня 14 API-референс був current і авто-регенерувався на code merge, runbook-покриття стало 85% з on-call інженерами що редагують кожен новий запис, а беклог design-doc перестав рости, бо у сеньйорів повернулося дві години на тиждень. Net-ефект: on-call інженери знаходили runbook до того як page закривався, а нові hires рампилися за 5 днів замість 3 тижнів, бо setup guide нарешті був точний. Design docs не покращилися — але і не погіршилися, і апетит команди їх писати повернувся.

Note on this case: Цей приклад ілюстративний — на основі типових патернів у компаніях 30-500 співробітників, не один названий клієнт. Конкретні числа — округлені наближення поширених діапазонів, не гарантії.

Tool tip (Course for Business): Те, що робить інженерний doc-adoption стійким — це названий AI Champion (1:15-20), що проводить щотижневий doc-by-doc review — що працює, що дрифтує, де людям треба забрати doc назад. Наша 6-тижнева програма явно вчить цьому ревʼю в тижні 4, з Shoulder-to-Shoulder hot seat, де champion сидить з eng-менеджером і проходить матрицю на реальних docs з repo команди. Запишіться на 30-хв mapping-дзвінок на https://course.aiadvisoryboard.me/business.

FAQ

Чи дати AI писати public-facing docs? Для reference (API docs, SDK guides) — так, з редакційним рев'ю. Для tutorial-контенту і концептуальних explainers, що формують, як клієнти розуміють продукт — ні, це позиціонувальні артефакти і потрібен людський голос.

А діаграми? AI зараз придатний для sequence diagrams і базових архітектурних, коли годуєш точним input-ом. Поганий на "на якому рівні абстракції ця діаграма" — та сама проблема судження, що в design docs. AI для чернетки, люди для вибору абстракції.

Чи якість AI-docs продовжить покращуватися? Так для reference і operational docs. Шар судження для design docs і ADR навряд закриється скоро — це не проблема якості моделі, це проблема доступу до контексту.

Як зупинити AI docs від субтильної неправильності? Дві речі. Перше — ланцюг джерела правди має бути щільним: AI читає код, не інші AI-згенеровані docs. Друге — "last regenerated" stamp має бути видимий читачам, щоб вони могли sanity-check проти кодбази.

А Notion/Confluence-style team docs (рішення, retros, project pages)? AI заповнює структуровані частини (timelines, status fields, generated summaries), narrative-частини лишаються людськими. Матриця поділу вище — зрозумій, яку роботу робить кожна doc, і маршрутизуй.

Висновок

AI-інженерна документація — не бінарна перемога чи бінарний провал. Це специфічний інструмент для специфічного шару — детермінований переклад коду, конфіг і алертів у прозу. Зроби цей шар правильно — і збережеш інженерам 30-90 хвилин на doc та отримаєш reference docs, які реально current. Спробуй розтягнути на design docs — отримаєш впевнено-звучне прісне, якому ніхто не довіряє.

Запустіть матрицю поділу docs цього тижня. Оберіть три типи, де даєте AI чернетити 100%. Оберіть три, де люди залишаються повністю відповідальними. Запишіть межу.

Якщо хочете, щоб кожен співробітник — включно з інженерами — зашипив свою першу AI-автоматизацію за п'ять днів із такою структурованою межею, забронюйте 30-хв дзвінок і ми мапнемо перший тиждень вашої команди на https://course.aiadvisoryboard.me/business.