The Diataxis Framework Explained: Four Types of Documentation

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

4 типи документації діатаксії

Type	Answers the question	Serves	Is oriented toward
Tutorial	”How do I get started?”	A learner	Learning
How-to guide	”How do I accomplish a specific goal?”	A practitioner	A goal
Explanation	”Why does this work the way it does?”	Someone seeking understanding	Understanding
Reference	”What is the exact specification?”	A practitioner who needs facts	Information

Tutorials

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

** Ключові характеристики: **

• Поступова, послідовна структура
• Завжди призводить до конкретного результату
• Пояснює лише те, що необхідно для виконання завдання — не пояснює теорію
• Не передбачає попередніх знань

** Словник для самостійного навчання: **

• • “У цьому навчальному курсі ви зможете…” *
• • “До кінця цього навчального курсу ви зможете…” *
• • « Виконати наступну команду… » *
• • “Ви повинні побачити наступний вивід…” *
• “Вітаю — ви успішно…”

** Поширена помилка: ** Перетворення навчального курсу на посібник з використання програми за допомогою можливості вибору. Навчальний посібник повинен приймати рішення за учня.

Використовує гітару

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

** Ключові характеристики: **

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

** Як- до- керівництво словниковим запасом: **

• “Щоб налаштувати X, виконайте такі дії:”
• • “Якщо вам потрібно Y, скористайтеся наступним підходом:” *
• *“Цей посібник припускає, що ви вже встановили…” *
• “Для пояснення, чому це працює, дивіться [документ з поясненням].”

** Поширена помилка: ** Включаючи пояснювальні абзаци, які читачеві не потрібні для виконання завдання. Замість цього, напишіть про це в документі з поясненнями.

Explanations

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

** Ключові характеристики: **

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

** Пояснювальний словник: **

• “Причина такого дизайну в…”
• “Історично, цей підхід виник з…”
• “Зрозуміти X вимагає розуміння Y спочатку.”
• “Есть три способа думать об этом…”
• “Компроміс між X і Y означає, що…”

** Приклад відкриття пояснення: ** * « Автентифікація у цій системі не має стану, тобто сервер не зберігає жодних даних щодо сеансу. Цей розділ пояснює, що це означає, чому він був розроблений таким чином, і які наслідки це має для того, як ви використовуєте API.”*

Reference

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

** Ключові характеристики: **

• Структуровано послідовно, щоб інформацію було передбачувано знайти
• Опис, а не інструкція
• Без жодних пояснень чи міркувань, просто факти
• Часто автоматично генерується з коду (наприклад, з.NET). API посилання, CLI довідковий текст)

** Довідковий словник: **

• • “Повертає… / Приймає… / Вимагає…” *
• • « Тип: рядок | ціле число | булівське значення » *
• • « Типовий: [значення] » *
• “Див. також: [пов’ язані записи]”

** Приклад запису посилання: ** ” max_retries (ціле число, необов’ язкове, типове: 3) — Максимальна кількість повторних спроб для невдалого запиту. Встановлення цього значення на 0 вимикає повторні спроби.”

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

Найціннішим використанням Diataxis є як ** діагностичний інструмент **. Якщо документ є заплутаним або не корисним, запитайте: чи намагається він бути двома речами одночасно?

• “Цей документ починається як навчальний посібник, а потім переходить до посилань у середині — саме тому його важко слідкувати. Розділимо його»

Відповідь на питання:

• • “Це навчальний посібник чи посібник з керування? Якщо читач вже знає основи, це посібник з початківцями». *
• • “Чи слід включити це пояснення до навчального матеріалу, чи це перерве процес навчання?” *
• • “Це покрокова інструкція, чи це інформація для пошуку? Посилання належить на окремій сторінці.»*

Приклади висловлювань

1. «Документація для впровадження в даний час змішує навчальний вміст з довідковим матеріалом — нові користувачі заплутуються, тому що вони не можуть сказати, що їм потрібно зробити, порівняно з тим, що їм може знадобитися подивитися»
2. «Як-до-посібник для цієї задачі є більш відповідним, ніж навчальний посібник — наші користувачі вже розуміють основи і просто потребують чіткий рецепт для конкретного сценарію»
3. «Пояснюючий документ для моделі авторизації повинен описувати рішення проектування і компроміси, а не кроки для його налаштування — це належить до посібника»
4. «Довідкова документація для CLI повинна бути автоматично створена з коду, щоб забезпечити його точність — вручну підтримувані довідкові сторінки мають тенденцію до дрейфу»
5. «Застосування структури Diataxis до нашого аудиту документації допомогло нам визначити, що у нас було 40 документів у стилі навчального посібника, але майже немає пояснень — саме тому користувачі розуміли, як почати, але змушені були зрозуміти, чому все працювало так, як вони робили»

Навигація Нуанси: Цільова мова для міжнародних команд

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

Розглянемо цей типовий сценарій: розробник, назовемо його Jian, надсилає запит на оновлення потоку автентифікації у нашій програмі. Опис PR просто: «Відомостями про автентифікацію». Хоча технічно це точно, але надзвичайно неоднозначно. Рідний англомовний мовець відразу б зрозумів контекст і обсяг зміни. Але для когось, хто все ще розвиває свій професійний словник, це може призвести до питань на кшталт: «Яка * конкретна * помилка була виправлена? Які кроки були вжиті для його вирішення?» Відсутність деталей створює неоднозначність і вимагає пояснень — можливо, сповільнюючи процес перегляду.

Аналогічно, під час перегляду коду, ви можете отримати коментар від Сари: « Цій частині потрібно більше контексту ». Не розуміючи, що означає « контекст » у цьому технічному середовищі, Цзян може відчути себе негайно підданим критиці або не впевненим у тому, як слід продовжувати. Важливо пам’ятати, що «більше контексту» не завжди означає додавання шарів жаргону; це часто вимагає чіткого пояснення * чому * було прийнято певне рішення і його вплив на загальну систему. Фрази на кшталт «Ця модифікація покращує продуктивність на X%» відразу зрозумілі, в той час як просто стверджуючи «Оптимізований код» залишає місце для плутанини і вимагає подальшого дослідження.

Сфокусироваться на точности в твоих описаниях - это ключ. Замість того, щоб сказати « Впроваджено обробку помилок », спробуйте сказати щось більш конкретне: « Додано надійну обробку помилок до кінцевої точки API, зокрема, записування у журнал докладних відомостей про винятки і впровадження механізму повторних спроб з експоненціальним відновленням ». Такий рівень докладності демонструє професіоналізм і активне вирішення потенційних питань. Пам’ятайте, будівництво сильної технічної лексики не просто про вивчення нових слів; Це про розуміння того, як ці слова використовуються в конкретному професійному контексті - такий, де ясність і недвозначне спілкування є найважливішими для успішного співробітництва. Не бійтеся просити про пояснення, якщо ви не впевнені в терміні або фразі, і завжди намагайтеся сформулювати свій процес мислення чітко і точно.