Навіщо потрібна документація: як рішення переживає автора

Вихідне питання

Навіщо програмі документація, якщо робочий код уже показує, що робить система?

У квітні 1943 року Роберт Сербер прочитав у Лос-Аламосі серію з п’яти лекцій для науковців, яких залучали до нового дослідницького центру. Їхній зміст став відомим як The Los Alamos Primer. Документ вводив новоприбулих фахівців у спільне завдання: фіксував вихідні уявлення про фізику ядерного вибуху, окреслював цілі роботи й давав колективу спільну мову.

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

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

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

Код зберігає дію, документ зберігає рішення

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

Найпростіший фрагмент виглядає самодостатньо:

if (failedAttempts >= 5) {
	lockAccount(user.id);
}

Код показує правило. Він не пояснює вибір п’яти спроб, модель загроз, тривалість блокування, допустиму ціну хибного спрацьовування, винятки для служби підтримки й підставу, за якою поріг можна змінити. Ці відомості могли існувати в розмові, завданні, листі або голові розробника. Система продовжить виконувати рішення після зникнення всіх чотирьох джерел.

Тести фіксують очікувану поведінку. Історія Git фіксує послідовність змін. Імена й коментарі пояснюють локальні фрагменти. Разом вони утворюють частину документації, але кожен із цих шарів відповідає на власне питання. Хронологія комітів іще не стає аргументом, а зелений тест не розкриває походження вимоги.

Корисна документація зберігає чотири види контексту:

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

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

Без цього зв’язку досвід швидко стає переказом. Рішення продовжує діяти, його підстави зникають, і команда починає захищати випадкову форму як природний закон. У програмуванні так народжуються священні друкарські помилки в API, тимчасові обхідні рішення десятирічної витримки й таблиці бази даних, до яких ставляться як до археологічного поховання: торкатися страшно, призначення втрачено, жертвопринесення в cron досі виконуються.

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

Між наміром і напругою

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

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

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

Кнут змінює адресата програми

У 1984 році Дональд Кнут сформулював цю проблему радикальніше за звичайний заклик писати більше коментарів. У статті Literate Programming він запропонував вважати головним адресатом програми людину, якій потрібно пояснити, що саме автор хоче доручити комп’ютеру.

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

Кнут реалізував цей принцип у системі WEB. Один вихідний файл поєднував текст документа й програмні фрагменти. Утиліта WEAVE створювала орієнтований на людину опис, а TANGLE збирала код для компілятора:

                    → WEAVE  → документ для людини
єдине WEB-джерело
                    → TANGLE → програма для машини

Ця схема розв’язує одну з найнеприємніших проблем документації: розходження двох версій правди. За наявності двох незалежних файлів код змінюється швидше за пояснення, а пояснення продовжує описувати систему, якої вже немає. WEB пов’язує обидві проєкції спільним джерелом і механізмом збирання.

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

Мета й межа методу

Мета документації полягає в передаванні наміру, перевірюваності рішення та здатності системи переживати зміну учасників. Ця мета задає власні пріоритети: ясність отримує перевагу над локальною швидкістю, спільний контекст — над особистою пам’яттю, відтворюваність — над надією на те, що «автор усе пам’ятає».

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

Сам Кнут прямо окреслював цю межу. Він попереджав, що досвід роботи з WEB забарвлений його особистими смаками, свідомо не проєктував мову для всіх і припускав, що метод особливо привабить програмістів, яким подобається писати й пояснювати свою роботу. Це застереження входить до самої моделі. Літературне програмування потребує часу, кількох мов, окремого процесу збирання та дисципліни єдиного джерела.

Повний literate-процес особливо виправданий у складних алгоритмах, дослідницьких обчисленнях, довготривалих системах, генераторах, предметних правилах, небезпечних операціях і проєктах із дорогою передачею контексту. Одноразова утиліта й очевидний CRUD-модуль зазвичай потребують легшої форми. Практичну межу визначає співвідношення двох цін: вартості пояснення зараз і вартості нерозуміння згодом.

Мінімальний документ рішення може залишатися коротким:

Намір: яку проблему розв’язуємо.
Обмеження: що вже задано середовищем і ризиками.
Рішення: що саме приймаємо.
Альтернативи: що відхилено й чому.
Перевірка: чим підтверджується результат.
Перегляд: яка подія знову відкриває рішення.

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

Що залишилося після WEB

Класичний WEB зберіг нішеве становище, а його центральне питання розподілилося між різними практиками. CWEB і noweb продовжують історично близьку лінію генерування коду з літературного джерела. Org Babel використовує споріднені механіки іменованих блоків і tangling. Quarto, Jupyter і R Markdown розвивають виконувані документи, у яких текст, код, обчислення та результат перебувають в одному публікаційному контурі.

Сучасна відтворюваність додає середовище. Контейнери, lock-файли залежностей, CI-пайплайни й описані команди збирання зберігають умови, за яких вихідний матеріал знову перетворюється на перевірюваний результат. Тут продовжує діяти тривога Кнута: джерело має пережити іншу машину, іншого виконавця та інший час.

Ці практики утворюють кілька споріднених ліній. Пряме продовження, інструментальна схожість і смислова асоціація потребують окремого оцінювання. Notebook не стає WEB лише через сусідство тексту й коду. Автоматично згенерований довідник API не стає літературною програмою. Кожен інструмент слід перевіряти за зв’язком між поясненням, реалізацією та відтворюваним артефактом.

Коли між людьми з’являється ШІ

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

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

TANGLE у Кнута детерміновано перетворював структуроване джерело. Велика мовна модель ймовірнісно створює кандидата на підставі контексту. Тому її результат отримує статус запропонованого артефакту й проходить перевірку:

людський пояснювальний план
  → контракти фрагментів
  → обмежений промпт
  → кандидат, створений ШІ
  → рев’ю
  → тести й smoke-перевірка
  → журнал походження та рішень
  → прийняте оновлення канонічного джерела

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

Висновок

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

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

Код зберігає дію системи. Документ зберігає рішення після того, як голос автора зникає.

Відомості про публікацію

Автори: Sam Starling, Oksana Dubinetska
Контекст проєкту: Zhovten Games / IRONCREED
Повний дослідницький матеріал: Literate Programming: Дональд Кнут, WEB і сучасні робочі процеси
Вихідна стаття Дональда Кнута: Literate Programming, The Computer Journal, 27(2), 1984
Пов’язаний метод: Prompt-Literate Workflow
Архівний матеріал вступу: Robert Serber, The Los Alamos Primer, OSTI
Характер дослідницької основи: незалежний методологічний огляд; препринт; не проходив рецензування
Редакція публікації: 1.0 · 2 серпня 2026 року