4 типи документації: Diátaxis Framework пояснено

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

** Диатаксічний механізм ** (створений Daniele Procida) вирішує це завдяки поділу всієї технічної документації на чотири окремі типи. Кожен тип обслуговує різні потреби користувача, має різну структуру і використовує різну мову. Змішування типів є найпоширенішою причиною плутанини у документації.

Знання Diátaxis робить вас значно кращим технічним письменником — і допомагає вам переглядати, структурувати і ефективніше виконувати документацію.

---

Чотири види на один погляд

Type	User’s goal	Analogy
Tutorial	Learning	A cooking class
How-to Guide	Doing a specific task	A recipe
Reference	Checking a fact	A dictionary definition
Explanation	Understanding a concept	An essay

У цій структурі ці значення відображено на двох осях:

• ** Практичні проти теоретичних ** (уроки/посібники проти посилань/пояснень)
• ** Вивчення проти роботи ** (уроки/ пояснення проти посібників/ посилань)

---

Тип 1: Підручник

Що це таке

Навчальний посібник — це досвід навчання. Для цього потрібні абсолютний початківець і повний, робочий досвід — а не всеохопний.

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

Когда его использовать

• Користувач повністю новий для вашого продукту
• Ви хочете зменшити бар’єр для початку
• Ви хочете встановити довіру перед складністю

Що це не так

• Посібник з використання (навчальні матеріали не вирішують справжніх проблем користувачів)
• Посилання (у навчальних посібниках не все задокументовано)
• Пояснення того, чому речі працюють так, як вони працюють

Structure

1. ** Почати з конкретного результату ** — що користувач зможе створити до кінця?
2. Зроби роботу за них - мінімальний вибір, конкретні інструкції
3. ** Пояснити необхідний мінімум ** — не пояснюйте внутрішні процеси під час навчання
4. ** Переконайтеся, що це працює ** — навчальний посібник, який зазнає невдачі, гірший за жодний навчальний посібник

Language

• Теперішній час, друга особа, дієслово
• Імперативні дієслова: “Створити файл. Виконати команду. Перейти до…""
• Короткі речення, одна дія на речення
• Заспокоїти: “Ви повинні тепер побачити… Якщо ви побачите помилку, перевірте…""

Приклад: Почати з CLI

# Getting Started with the Acme CLI

By the end of this tutorial, you will have:
- Installed the Acme CLI
- Created your first project
- Deployed it to staging

This takes about 15 minutes.

## Step 1: Install the CLI

Run the following command in your terminal:

npm install -g acme-cli

You should see output like this:
+ acme-cli@2.1.0 added

## Step 2: Create a project

acme create my-first-project

When prompted, select the "basic" template.

Navigate into your new project directory:

cd my-first-project

You now have a working project. Let's deploy it.

---

Тип 2: Як-так-на-керівництво

Що це таке

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

Як я можу встановити аутентифікацію? Як я розгортаю виробництво?» Як я налаштовую змінні середовища?

Когда его использовать

• Користувач має конкретну мету, яку він має досягти зараз
• Вони не починають з нуля - вони мають контекст
• Задача має визначений початок і кінець

Що це не так

• Навчальний посібник (в ньому передбачається досвід, але він не надає його)
• Посилання (не містить вичерпної документації щодо параметрів)
• Пояснення (не пояснює * чому * — тільки * як *)

Structure

1. ** Заголовок вказує на мету **: « Як налаштувати сертифікати SSL »
2. ** Попередні вимоги ** (короткий перелік): те, що потрібно користувачеві перед початком роботи
3. ** Кроки **: нумеровані, імперативні, конкретні
4. ** Результат **: як виглядає успіх

Language

• Імперативні дієслова (такі ж, як у підручниках)
• Мінімальне пояснення * чому * — читач знаходиться у режимі завдання
• Якщо крок здається несподіваним, одне речення контексту прийнятно
• Припустити компетентність: пропустіть основні пояснення, які ваша аудиторія вже знає

Приклад: Як повернути розгортання

# How to Roll Back a Kubernetes Deployment

**Prerequisites:** kubectl configured with cluster access, deployment name

## Steps

1. Check the rollout history to identify the target revision:
   kubectl rollout history deployment/my-service

2. Roll back to the previous revision:
   kubectl rollout undo deployment/my-service

   To roll back to a specific revision:
   kubectl rollout undo deployment/my-service --to-revision=3

3. Verify the rollback is complete:
   kubectl rollout status deployment/my-service

   You should see: "successfully rolled out"

4. Confirm the correct version is running:
   kubectl describe deployment/my-service | grep Image

---

Тип 3: Посилання

Що це таке

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

Когда его использовать

• Документування API, CLI, файла налаштувань або схеми даних
• Надає повний список параметрів, параметрів або значень
• Створення матеріалу, який інженери будуть шукати під час роботи

Що це не так

• Навчальний посібник (не веде, а інформує)
• Посібник з налаштування (не містить кроків)
• Пояснення (не містить контексту або обґрунтування — лише факти)

Structure

• Послідовний формат (часто таблиця або структурований список)
• Повне покриття (всі параметри, всі краї)
• Без розповіді - просто факти

Language

• Декларативний, а не імперативний
• Теперішній час: “Повертає об’ єкт користувача. Приймає два аргументи.”
• Немає суб’єктивної мови: не “Це корисний параметр” — просто вкажіть, що він робить

Приклад: API Endpoint Reference

## POST /users

Creates a new user account.

### Request body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| email | string | Yes | Must be a valid email address. Maximum 254 characters. |
| password | string | Yes | Minimum 8 characters. |
| name | string | No | Display name. Maximum 100 characters. Defaults to email prefix. |
| role | enum | No | `user` or `admin`. Defaults to `user`. |

### Response

**201 Created**
Returns the created user object.

**400 Bad Request**
Returned when required fields are missing or fields fail validation.

**409 Conflict**
Returned when the email address is already registered.

---

Тип 4: Пояснення

Що це таке

Пояснення (або «обговорення») забезпечує ** фонове розуміння **. Вона відповідає на питання “чому” і “як це працює”, а не “як це використовувати”. Це найбільш забутий тип технічної документації.

Когда его использовать

• Пояснення проектних рішень, що стоять за архітектурою
• Надання контексту, який пояснює, чому інструмент працює так, як він працює
• Покриття компромісів, обмежень і альтернатив
• Запис ADR (запис рішення архітектури)

Що це не так

• Навчальний посібник (не містить інструкцій щодо дії)
• Посібник з виконання (це не допоможе вам виконати завдання зараз)
• Посилання (не містить фактів)

Structure

• Може бути вільною формою, в стилі есе
• Використовує заголовки розділів для навігації
• Можна включати діаграми, порівняння, таблиці з порівняннями

Language

• Дискурсивний і дослідницький
• “Це тому, що…”, “Причина, чому ми обрали…”, “Загальна альтернатива -…”
• Перша особа множини прийнятна: “Ми вирішили…”
• Може включати невизначеність: “Цей підхід добре працює для X, але має проблеми з Y.”

Приклад: чому ми використовуємо Event Sourcing

## Why We Use Event Sourcing in the Orders Service

The orders service stores all state changes as an immutable event log 
rather than updating records in place. This section explains the reasoning 
behind this choice and the trade-offs involved.

### The problem with mutable state

Traditional CRUD systems store only the current state of an entity. When 
an order changes from "pending" to "paid", the database record is updated. 
This means the history of how an order reached its current state is lost.

For financial transactions and audit requirements, this creates problems...

### Why event sourcing fits our context

Orders are naturally a sequence of events: created, payment initiated, 
payment confirmed, warehouse notified, shipped, delivered...

### Trade-offs

Event sourcing requires an event store, adds complexity to reads (projection 
required), and makes debugging more involved. These costs are justified for 
orders because...

---

Найбільш поширена помилка документації

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

Класичні приклади змішаного типу:

1. Відео з вставленим посиланням — “Run npm install. Прапорець --save додає пакунок до package.json. Зауваження: npm також підтримує --save-dev для залежностей розробки. Прапорець --no-optional пропускає необов’язкові залежності. Ви також можете використовувати yarn add.” → Урок зірвався в посилання документації. Читач навчається, але зараз його переповнюють варіанти.

2. Посібник з поясненнями — “Натисніть кнопку Розгорнути. Процес розгортання працює за допомогою контейнеризації програми за допомогою Docker, який був обраний над Podman через його поширене прийняття. Потім контейнер відсилається до ECR. Натисніть Розгорнути.” → Читач хоче розгорнути, а не прочитати есе про Docker.

3. ** Довідка, яка намагається бути навчальним посібником ** — документація API, яка прокладає вам шлях повним сценарієм, замість того, щоб перераховувати параметри нейтральним чином.

** Виправлення: ** Перед написанням будь- якого розділу, запитайте: * « Який тип документації це?» * Якщо це навчальний посібник, вилучіть вміст посилання. Якщо це посібник, то вилучіть пояснення. Написати кожен тип окремо і зв’ язати їх між собою.

---

Швидкий ідентифікаційний тест

Якщо ви не впевнені, який тип вам потрібен, задайте такі запитання:

1. Чи читач вчиться або робить? → Навчання = вчитель/пояснення, Робити = як-до/посилання
2. Чи читачеві потрібні кроки або факти? → Кроки = вчитель/як-до, Факти = посилання
3. Чи читач початківець або досвідчений? → Початківець = навчальний посібник, Досвідчений = як-до/посилання
4. Чи документ потребує розповіді? → Так = навчальний посібник/пояснення, Ні = як-до/посилання

---

Використовується в практиці

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

• ** Початкова інформація ** → Навчальний посібник (один повний поток)
• ** Guides / How- To ** → Посібники (засновані на завданні, з можливістю пошуку за метою)
• ** Довідка щодо API ** → Довідка (повна, послідовна, з можливістю навігації)
• ** Концепції / Архітектура ** → Пояснення (глибоке тло)

Цей файл відображається майже на кожному успішному сайті документації для розробників: Stripe Docs, Kubernetes Docs, Django Docs, AWS Documentation.

---

Зв’язані ресурси

• Введення в технічну літературу
• Активний проти. Співавтор технічної літератури
• Писання документації API англійською