Технічна документація — це не другорядне завдання, яке ви виконуєте після того, як код скомпілювався. Вона стоїть у центрі кожного програмного проєкту, визначаючи, чи зможе новий розробник виправити помилку у свій перший день, чи користувач покине ваш продукт через п'ять хвилин розгубленості. Хороша документація допомагає користувачам виконувати реальні завдання. Вона допомагає майбутнім супроводжувачам зрозуміти, навіщо існує модуль і як його змінити, не зламавши все інше. Проте занадто багато команд ставляться до документації як до другорядного фактора: як до README, написаного на поспіху, або сторінки у wiki, що поступово занепадає. Написання справді корисної документації — це навичка, яку можна цілеспрямовано вдосконалювати.
Знайте своїх читачів перед тим, як писати
Перш ніж надрукувати хоча б один заголовок, вирішіть, хто саме читає. Адміністратор бази даних, який шукає налаштування пулу з'єднань, не має нічого спільного з фронтенд-розробником, який шукає пропси React-компонентів. Кінцевим користувачам потрібні покрокові інструкції та скриншоти, а не діаграми архітектури. Вони хочуть знати, як експортувати PDF, а не те, як працює конвеєр рендерингу. Розробникам, які інтегрують вашу бібліотеку, потрібні точні сигнатури функцій, коди помилок і фрагменти коду, які можна скопіювати та вставити. Системним адміністраторам потрібні попередні вимоги до встановлення, змінні оточення та алгоритми усунення несправностей, що починаються з найпоширеніших сценаріїв відмови.
Якщо ви спробуєте обслуговувати всі три групи одним суцільним текстом, програють усі. Створюйте окремі шляхи. Навіть одну сторінку можна чітко сегментувати за допомогою зрозумілих заголовків, таких як «Для операторів» та «Для клієнтських розробників». Мета полягає в тому, щоб усунути когнітивне навантаження від запитання: «Цей абзац призначений для мене?»
Відсікайте зайве
Чіткість важливіша за вигадливість. Використовуйте короткі речення. Використовуйте активний стан. «Ініціалізуйте базу даних» — зрозуміліше, ніж «База даних має бути ініціалізована користувачем». Коли ви змушені використовувати технічний термін, як-от «idempotency» або «serialization», визначте його безпосередньо в тексті або надайте посилання на глосарій. Не припускайте наявності попередніх знань.
Один практичний тест: спробуйте прочитати свій абзац вголос. Якщо вам бракує подиху, речення занадто довге. Інший тест: замініть пишні дієслова простими. Якщо фразу на кшталт «utilize the API» можна замінити на «use the API» без втрати змісту, зробіть це. Проста мова не означає примітивну мову. Це означає точну мову, позбавлену корпоративної «води».
Структура, що справді допомагає
Неорганізований посібник витрачає більше часу, ніж його відсутність. Думайте про свою документацію як про воронку. На самому верху розмістіть короткий огляд, який пояснює, що робить проєкт і кому він може бути цікавий. Далі йдуть інструкції з інсталяції, які нічого не припускають щодо локального середовища читача. Потім додайте навчальні посібники (tutorials), які проводять через повні, реалістичні сценарії від початку до кінця. Далі йдуть довідники API. Вони мають бути вичерпними, але зручними для швидкого перегляду, згрупованими за ресурсами або функціями, а не просто викладеними в алфавітному порядку. Нарешті, розмістіть посібники з усунення несправностей, які стосуються конкретних симптомів. Користувачеві, який отримує «Connection refused», потрібна інша відповідь, ніж тому, хто бачить «Permission denied». Групуйте помилки за повідомленням або контекстом, а не за абстрактною категорією.
Списки та блоки коду розбивають щільний текст і дозволяють читачам швидко знаходити потрібну команду. Добре розміщений маркований список може перетворити абзац плутанини на послідовність дій.
Показуйте, а не просто розповідайте
Абстрактні пояснення дратують користувачів. Якщо ви описуєте, як налаштувати інструмент, покажіть точний вміст файлу. Надайте фрагменти коду для встановлення, ініціалізації та типових конфігурацій. Покажіть зразки вхідних даних і очікуваних результатів поруч. Якщо ваш API повертає JSON, покажіть JSON. Якщо інструмент командного рядка (CLI) видає табличний вивід, покажіть таблицю. Ніколи не вважайте, що опис робочого процесу є еквівалентним демонстрації.
Найголовніше — протестуйте кожен приклад у чистому середовищі перед публікацією. Скопіюйте власний фрагмент коду в новий контейнер або віртуальну машину. Якщо він не спрацює через те, що ви забули згадати про залежність, ви врятуєте себе від потоку звернень із проблемами. Конкретні приклади забезпечують найбільшу окупність інвестицій у технічне письмо, оскільки вони перетворюють невпевненість на дію.
Підтримуйте її в актуальному стані
Документація застаріває швидше за код. Змінюється сигнатура методу, змінюється порт за замовчуванням, замінюється залежність — і раптом ваші інструкції ведуть у глухий кут