Підтримка й ефективність

Підтримка документації: як не дати опису відстати від системи

Команда змінила команду запуску, оновила контракт API (Application Programming Interface — інтерфейс прикладного програмування), змінила дозволи або…

Глава 65Заморожене українське видання

Команда змінила команду запуску, оновила контракт API (Application Programming Interface — інтерфейс прикладного програмування), змінила дозволи або перейшла на інше сховище. Код уже працює за новими правилами, а README, інструкція для агентів і план розгортання все ще описують старі правила. Така розбіжність — не косметична помилка: вона змушує людей і автоматизованих помічників приймати рішення за вигаданим станом системи.

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

Навчальний результат. Читач може визначити документи, яких стосується зміна; призначити власника й джерело твердження; відрізнити історичне рішення від чинної інструкції; перевірити актуальність, версію й межі застосування; зробити обмежене, доказове оновлення без вигадування поведінки.

65.1. Документація описує певну версію реальності

Документ не стає істинним через те, що його написано в Markdown, збережено в Git чи затверджено в запиті на злиття (pull request, PR). Щоб на твердження покладатися, треба знати систему, версію, конфігурацію, аудиторію й дату, про які йдеться, а потім звірити їх із відповідним джерелом.

Команда npm test неповна, якщо репозиторій перейшов на pnpm, не вказано робочий каталог або потрібна окрема база даних. Фраза «сервіс шифрує резервні копії» не пояснює, чи це гарантує сам продукт, зовнішнє сховище або конфігурація оператора. Твердження «Claude читає AGENTS.md» може стосуватися Claude Code певної версії й налаштування, але не всіх продуктів Anthropic.

Тип розбіжності Що застаріло Можливий наслідок
Командна команда, каталог, прапорець або залежність команда не запускається чи змінює не той ресурс
Контрактна схема, формат, гарантія чи код помилки інтеграція відхиляє дані або неправильно обробляє результат
Процедурна порядок кроків, умова зупинки, дозвіл чи відновлення оператор поглиблює збій або не може безпечно відкотити дію
Статусна задум або план подано як поточний факт хтось виконує скасовану роботу чи вважає функцію готовою
Архітектурна старе рішення не позначене як замінене команда продовжує будувати на відкинутому припущенні
Меж застосування версія, платформа, тариф чи режим приклад з одного середовища застосовують до іншого
Навігаційна старе посилання чи прихований актуальний текст читач звертається до копії або архіву

Розрізняйте неправильне твердження, невказану межу, прогалину та історичний опис. «Підтримуються лише Linux і macOS» не застаріло, якщо це досі точна межа, хоч Windows уже заплановано. Точний статус важливіший за довжину документа.

65.2. У кожного документа свій життєвий цикл

README пояснює, як почати роботу; довідник API описує чинний контракт; запис архітектурного рішення зберігає мотиви вибору в минулому. Переписати старе рішення так, ніби його не приймали, — знищити історію. Залишити старий активний план без статусу — змусити читача вважати його чинним.

Документ Запитання читача Тригер перегляду Завершення або заміна
README і вступ Що це і як запустити? зміна запуску, вимог чи основної функції оновити шлях; старий прибрати або обмежити
Довідник API Якого контракту дотримуватися? зміна схеми, поведінки, доступу чи сумісності описати підтримувані версії
Запис архітектурного рішення (Architecture Decision Record, ADR) Які варіанти й компроміси розглядали? нове рішення чи перегляд передумови новий запис посилається на старий; старий зберігає історію
Активний план Що заплановано й виконано? зміна пріоритету, власника, строку чи обсягу позначити виконаним, скасованим або заміненим
Runbook, операційна процедура Як безпечно виконати відому дію? зміна команд, доступів або відновлення перевірити кроки в визначеному середовищі
Політика Які правила й винятки обов’язкові? зміна ризику, контролю чи вимоги зафіксувати затвердження, чинність і заміну
Навчальна глава Який принцип і приклад допомагають діяти? зміна продукту, інтерфейсу, функції чи посилання зберегти принцип; позначити версію прикладу

Статуси на кшталт «чернетка», «чинне», «замінене» й «архів» корисні, якщо їх визначено й індекс веде до правильної версії. Відокремлюйте статус сторінки від статусу функції: чинна документація може правильно сказати, що функція недоступна.

Amazon Web Services (AWS) Prescriptive Guidance радить не переписувати прийнятий ADR заднім числом. Новий запис фіксує новий вибір, а попередній отримує статус «замінений» (superseded) і посилання вперед. Це порада AWS, а не єдиний формат ADR. AWS: ADR process

65.3. Власник потрібен твердженню, а не папці

Фраза «документація належить команді» не пояснює, хто перевірить поведінку після зміни коду. Власник — людина чи роль, здатна підтвердити зміст і організувати виправлення. Власник сторінки може не володіти кожним фактом, тому сторінка має вказати відповідального за критичний контракт і його джерело.

Зміна Хто перевіряє Що звіряє
Команда тесту, ціль, залежність чи прапорець супроводжувач збірки команду, версії інструментів, чисте середовище
Поле API, схема події, помилка власник контракту/API схему, сумісність, приклади й семантику
Резервна копія чи сховище власник даних/процедури фактичний артефакт, відновлення й версію
Дозволи, секрети чи персональні дані власник контролю та технічний фахівець де діє контроль, винятки й журналювання
Архітектурне рішення автор нового рішення чи призначений власник альтернативи, наслідки й попередні записи
Приклад інтерфейсу продукту автор прикладу чи викладач джерело, версію, режим і межі функції
Аварійна процедура відповідальний за експлуатацію кроки, умови зупинки, права й результат

Тригери можна закріпити в рев’ю: зміна конфігурації тесту вимагає перегляду команди в README; зміна схеми — довідника й прикладів; зміна дозволу — процедури та політики. CODEOWNERS у GitHub маршрутизує запит на рев’ю до власників змінених файлів, але не доводить, що власники чинні чи текст правильний. GitHub: About code owners

Для критичних сторінок зафіксуйте роль власника, джерело, тригери перегляду, охоплені версії й дату змістовної перевірки. Починайте з інструкцій, що можуть вплинути на запуск, дані, дозволи, безпеку чи рішення про готовність.

65.4. Зв’язуйте зміни документації зі змінами системи

Документація як код (docs as code) зберігає текст у версійованому репозиторії й дає історію, порівняння, рев’ю та автоматичні перевірки. Це не гарантує, що автор звірив опис із поведінкою.

Будуйте ланцюжок: зміна в джерелі → твердження, що змінилося → залежні документи → перевірка кожного оновленого твердження. Перехід команди тестів у package.json може зачепити README, інструкцію для агентів і шаблон внеску. Він не вимагає переписувати всі глави чи історичні звіти. Оновлюйте саме ті місця, де лишився старий факт або залежність від нього.

Коли документація й код змінюються в одному PR, рецензент бачить контракт, новий опис і перевірки разом. Якщо код уже об’єднано, створіть обмежене завдання на документацію, прив’яжіть його до зміни й призначте власника. «Оновимо пізніше» без відповідального й строку не закриває розбіжність.

У процесі GitHub Docs автор перевіряє технічну точність, стиль, версіонування, відображення таблиць і списків та результати перевірок; великі пропозиції можна спершу обговорити в issue. Це процес самого GitHub, не загальний регламент, але він показує, що контентне рев’ю має перевіряти зміст і рендеринг. GitHub: About contributing to GitHub Docs

Приклад спільної зміни коду й пояснення — Pydantic PR №7800. Issue №7784 повідомляв, що модель із параметром frozen=True, який забороняє змінювати поля, усе ж дозволяла видалити атрибут. PR додав перевірку видалення до реалізації, тест і приклад помилки в довідник, а його метадані закривають issue. Це показує користь спільної зміни поведінки, тесту й документа, але не доводить гарантій поза перевіреним випадком. Issue #7784; PR #7800

PR має пояснювати: яку проблему виправляє; яке твердження змінює; яке джерело підтверджує текст; для якої версії він правильний; як перевірено команди, приклади й рендеринг; що лишилося невідомим чи поза обсягом. Замість загального посилання на код вкажіть конкретну схему, файл, тест чи реліз, які звіряли.

65.5. Генеруйте факти, зберігайте людське пояснення

Генерація зменшує розбіжності для деталей з єдиним машинно-читаним джерелом. Вона не вирішить, який компроміс прийняла команда, чому діє обмеження або що робити в небезпечному випадку.

Зміст Доречно генерувати Лишити авторським
Поля, типи й кінцеві точки API довідник зі схеми контракту семантику, сумісність, бізнес-приклади
Параметри командного інструмента список прапорців з реалізації безпечний порядок і наслідки ризикових параметрів
Налаштування назви й типи зі схеми пріоритети, комбінації, межі підтримки
Пакети й інтеграції список із lock-файла причину вибору, ризик і процес оновлення

Довідник може показати, що status — рядок, але не пояснити, чи pending означає «запит у черзі» або «операція скасовна». Перелік прапорців може включити force, але не розповісти, що він обходить перевірку цілісності даних. Це частина контракту й ризику.

Генератор має запускатися з конкретної ревізії, а результат — зберігати походження: джерело, команду та, за можливості, версію інструмента. Зміна джерела без оновлення похідного файла має давати помітну різницю чи помилку. Не редагуйте вручну файл, який генератор перезапише. Канонічним джерелом може бути код, контракт або затверджена політика.

65.6. Перевіряйте зміст, не лише те, що легко автоматизувати

Успішна перевірка посилань показує, що адреса відповіла; вона не доводить, що сторінка правильна чи відповідає потрібній версії. Орфографічна перевірка не звіряє контракт.

Перевірка Що підтверджує Чого не підтверджує сама
Побудова сайту й рендеринг структура та відображення фактичну точність
Перевірка посилань шлях існує або адреса відповіла зміст сторінки й актуальність
Запуск прикладу в чистому середовищі команда працює за конкретних умов підтримку всіх платформ
Звірка API-прикладу зі схемою форму й частину поведінки семантику кожного сценарію
Перевірка термінів і версій неузгоджені назви чи старі мітки правильність контексту
Рев’ю власника перевірку відповідальною людиною незмінність факту надалі

Для команди зафіксуйте версію середовища й очікуваний результат або назвіть неперевірену платформу. Небезпечні кроки не запускайте на продуктивній системі заради позначки «перевірено»: використовуйте безпечне середовище або звіряйте код і передумови. Для процедури відновлення може бути потрібна репетиція відновлення, не лише перевірка команди створення копії.

Семантичне рев’ю питає: чи обіцяє сторінка те саме, що реалізація; чи видно версію; чи не узагальнено приклад з однієї платформи; чи знає читач, коли зупинитися; чи веде точка входу до чинної процедури? GitHub Docs версіонує матеріал за продуктами й релізами та радить перевіряти відповідні відображені варіанти. Ширший принцип той самий: називайте охоплену версію і перевіряйте кожен важливий варіант. GitHub: Versioning documentation

Зелена збірка чи перевірка посилань не підтверджує, що текст відповідає реалізації, називає потрібну версію й веде до чинної процедури.

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

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

Запис джерела має містити точне посилання чи локальний артефакт; клас джерела — код, тест, контракт, офіційний посібник чи припущення; обсяг — продукт, версію, платформу й середовище; дату фактичної перевірки; невизначеність, якої джерело не усуває.

Не ставте нову дату «перевірено» після зміни пунктуації, перекладу чи автоматичного перефразування, якщо джерело не відкривали. Коли змінилася лише форма, дата змістовної звірки лишається старою. Перенаправлення на нову адресу доводить, куди веде посилання, але не доводить, що зміст не змінився.

У навчальному матеріалі відокремлюйте сталу ідею від мінливого прикладу: назва файла, поведінка продукту й параметр мають версію та дату; принцип може лишатися чинним. Повторно перевіряйте зовнішню сторінку перед новим використанням прикладу.

65.8. Спільні інструкції для Claude Code і Codex

У репозиторії з кількома програмними агентами повторені інструкції розходяться: один файл наказує npm test, інший — pnpm test; один називає каталог генерованим, інший — редагованим. Коли вони конфліктують, агент може непомітно обрати одну версію.

Почніть зі спільних канонічних фактів: як зібрати проєкт, де міграції, які каталоги генеруються, які правила безпеки чинні й де архітектурна довідка. Якщо інструмент підтримує імпорт або посилання, зберігайте факти в одному місці та додавайте короткі специфічні вказівки. Якщо ні — тримайте копії короткими й змінюйте їх разом. Не дублюйте повні довідники в агентських інструкціях.

Механізми залежать від продукту. Документація OpenAI описує, як Codex читає AGENTS.md, враховує глобальні та проєктні інструкції й застосовує ближчі правила; огляд налаштувань відокремлює інструкції проєкту від пам’яті, навичок, серверів MCP (Model Context Protocol) і субагентів. OpenAI: AGENTS.md; OpenAI: Customization

Документація Anthropic про Claude Code зазначає, що пряме читання AGENTS.md потребує версії 2.1.277 або новішої; окремі типи сесій до версії 2.1.281 читали лише файли CLAUDE.md. За замовчуванням Claude Code читає AGENTS.md лише коли в робочому каталозі й батьківських немає CLAUDE.md чи CLAUDE.local.md; інакше читаються CLAUDE.md-файли, зокрема CLAUDE.local.md. Явне налаштування Project instructions може завантажувати обидва типи файлів. На поведінку впливає також вбудований плагін agents-md. Не узагальнюйте це до «Claude підтримує AGENTS.md» для всіх продуктів, версій і режимів. Перевіряйте конкретний продукт, версію та налаштування. Anthropic: Claude Code memory

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

65.9. Полегшуйте пошук чинного опису

Правильний текст, захований у старому плані, практично недоступний. Точка входу має назвати чинний матеріал і його призначення. Завершений план позначте статусом і датою або перемістіть в архів.

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

Збережіть старий ADR, план чи runbook, якщо він пояснює минуле рішення, але позначте історичним і посилайтеся на заміну. Якщо це лише дубль без історичної цінності, приберіть його або замініть переходом.

65.10. Реальний випадок: інструкція відновлення Gitea

Issue №25878 описує користувача Gitea 1.17.3, який відновлював систему за опублікованою процедурою й повідомив про розбіжність назв і шляхів в архіві та посібнику. Також з’явилася помилка про дубльовані індекси бази. Сам автор issue зазначав, що вже ініціалізована база могла впливати на результат і треба встановити вихідну версію. Це повідомлення користувача, а не повний аналіз помилки бази. Gitea issue #25878

Пов’язаний PR №26902 оновив лише сторінку резервного копіювання й відновлення: узгодив опис вмісту архіву, переніс шлях до app.ini до кореня архіву й виправив назви каталогів репозиторіїв для різних способів встановлення. Він не доводить, що причину помилки бази встановлено або що перевірено кожну версію й сценарій. Gitea PR #26902

Робочий процес: встановити версію й крок; звірити інструкцію з артефактом цієї версії; розділити спостереження та пояснення; виправити відповідні фрагменти; перевірити охоплені варіанти; повернутися до повідомлення користувача. Не заявляйте ширший успіх, ніж підтверджує перевірка.

Урок обмежений: невідповідність структури архіву посібнику може призвести до помилкової дії під час відновлення. Один issue не доводить, що весь посібник застарів або що кожен інший симптом має ту саму причину.

65.11. Навчальний випадок: ADR про базу даних застарів

Припустімо, ADR 12 рекомендував PostgreSQL для першої версії сервісу. Через рік вимоги змінилися, команда перевірила альтернативи й обрала інший рушій. Не переписуйте ADR 12 так, ніби старого рішення не було.

Новий ADR 27 пояснює причину перегляду, вимоги, альтернативи, компроміси та межі міграції. Він посилається на ADR 12 і позначає його заміненим. Індекс показує чинне рішення. README й інструкція розгортання описують поточну схему. Старий план стає завершеним лише після перевірки переходу. Якщо міграція триває, зазначте, які середовища вже перейшли, що лишилося, де джерело запису й яка умова завершення.

Звірте конфігурацію, схему, міграції, резервування та відновлення. ADR зберігає історію; чинна процедура живе там, де користувач шукає дію.

65.12. Документація продукту змінилася: Claude Code

Під час перевірки 10 жовтня 2026 року стара адреса сторінки пам’яті Claude Code перенаправляла на поточну сторінку. Перенесення адреси — лише перший факт для перевірки.

Поточна документація каже, що Claude Code читає AGENTS.md безпосередньо від версії 2.1.277. До 2.1.281 окремі сесії, зокрема через Amazon Bedrock або з вимкненою телеметрією, читали тільки файли CLAUDE.md. За замовчуванням AGENTS.md читається, якщо в робочому каталозі та його батьківських каталогах немає CLAUDE.md, .claude/CLAUDE.md чи CLAUDE.local.md; налаштування Project instructions claude-md-and-agents-md може завантажити обидва типи файлів. Якщо вбудований плагін читання AGENTS.md вимкнений, залишаються лише файли CLAUDE.md.

У поточній конфігурації це налаштування зберігається в pluginConfigs. До Claude Code 2.1.285 вбудований плагін мав ідентифікатор agents-md@builtin; у 2.1.285 його змінили на cc-plugin-agents-md@builtin, а поточна документація зазначає, що новіші версії читають налаштування під обома ідентифікаторами. Тому старе твердження «Claude Code читає лише CLAUDE.md» неповне для новіших версій і конфігурацій, а фраза «Claude читає AGENTS.md» надто широка. Перевіряйте саме продукт, версію, налаштування та записи конкретного запуску.

Обмежене оновлення курсу має перевести посилання на офіційну сторінку; вказати, що йдеться саме про Claude Code; назвати підтверджені версію й налаштування; зберегти сталу ідею; перевірити приклад у відповідній конфігурації. Не робіть старий знімок екрана необхідним для розуміння. GitHub Docs радить не версіонувати дрібниці, які не впливають на розуміння, але перевіряти варіанти, де поведінка відрізняється. GitHub: Versioning documentation

Тут дві окремі причини ревізії: адреса джерела змінилася, а підтримка функції розширилася. Оновити лише адресу — зберегти застарілий зміст. Оновити тільки речення без меж версії — надмірно узагальнити факт.

65.13. Робоча послідовність для доказового оновлення

  1. Зафіксуйте проблему: поточний текст і те, що, ймовірно, змінилося.
  2. Знайдіть джерело: код, контракт, конфігурацію, реліз чи офіційну сторінку.
  3. Встановіть межі: продукт, версію, платформу, прапорець, дозволи й середовище.
  4. Знайдіть залежні документи: точну команду, назву, факт чи шлях; відділіть активний текст від історії.
  5. Оновіть канонічне місце й посилання: видаліть дубль, зберігши історію, якщо вона пояснює рішення.
  6. Перевірте: запустіть приклад безпечно або звірте з кодом чи контрактом; перегляньте рендеринг і навігацію.
  7. Позначте межу доказу: залиште джерело й дату фактичної перевірки; невідомому призначте власника.
  8. Перегляньте обсяг: узгодьте пов’язані місця, приберіть дублікати й не переписуйте історію.
  9. Залучіть рецензента: власник перевіряє факт, редактор — зрозумілість і навігацію.

Готовий документ дозволяє знайти правильну інструкцію, побачити межі застосування та джерело, відрізнити факт від припущення. Свіжа дата й зелена перевірка посилань не замінюють цих ознак.

Джерела й межі перевірки

Наведені сторінки перевірено 24 вересня 2026 року. Офіційні керівництва описують практики їхніх авторів і продукти, а не універсальні вимоги. Issue та PR Pydantic і Gitea ілюструють конкретні випадки, але не доводять причинність поза описаними межами.

Зміст зовнішніх сторінок може змінитися після дати доступу. Перед повторним використанням прикладу звірте джерело й версію; не переносьте дату перевірки автоматично.