Diátaxis на практике: как разделить документацию на четыре жанра

26 февраля 2026 г. 14K

Проект разрастается. Документация — частично в README, частично на Wiki, частично в коде, и ещё какие-то страницы команда написала когда-то на Notion. Когда разработчик ищет ответ на конкретный вопрос, он прыгает между четырьмя источниками и в итоге пишет в Slack.

Diátaxis — это не очередной фреймворк документации с тулзой, конфигом и интеграциями. Это способ разделить документацию по типам так, чтобы каждая страница работала на свою задачу. На бумаге всё выглядит просто: четыре квадранта, четыре жанра, разнеси страницы по ним. На практике первый раз внедрить Diátaxis на живом проекте больно. Разберу, как это сделать на проекте, где документация уже есть, и не сломать процесс.

Что такое Diátaxis в двух абзацах

Diátaxis выделяет четыре типа документации по двум осям: «практический vs теоретический» и «изучение vs работа».

Tutorials — практические + изучение. «Сделай первое приложение». Для новичков.
How-to guides — практические + работа. «Как настроить CORS». Для решения конкретной задачи.
Reference — теоретические + работа. «Список параметров функции X». Для уточнений.
Explanation — теоретические + изучение. «Архитектура системы аутентификации». Для глубокого понимания.

Идея — не смешивать жанры на одной странице. Нельзя одновременно учить новичка и быть полным справочником. Нельзя одновременно объяснять архитектуру и давать пошаговую инструкцию.

Как выглядит проект до Diátaxis

Типичный сценарий:

README.md — getting started + установка + примеры + философия проекта + список всех функций.
Wiki — гайды по конкретным задачам + объяснения концепций + дублирующий getting started.
docs/api.md — reference, частично сгенерированный из docstring, частично руками.
Personal Notion-страницы команды — заметки по архитектуре, ADR, обсуждения.

Один и тот же вопрос «как настроить кеш» имеет ответы в трёх местах, все три немного отличаются, два устарели. Новый сотрудник тратит неделю, чтобы понять, что где искать.

Аудит текущего состояния

Первый шаг — не «всё переписать», а понять, что есть. Я обычно делаю простую таблицу:

| Page                    | Source        | Type       | Up-to-date? |
|-------------------------|---------------|------------|-------------|
| Getting Started         | README        | Tutorial   | yes         |
| API Reference           | docs/api.md   | Reference  | partial     |
| Configure CORS          | Wiki          | How-to     | yes         |
| Architecture overview   | Notion        | Explanation| no, 6 mo old|
| Cache invalidation      | Wiki          | Mixed      | partial     |
| First app deploy        | README        | Tutorial   | yes         |
| List of all settings    | docs/api.md   | Reference  | yes         |

Без аудита план миграции — это «посмотрим, как пойдёт». Со списком — план становится конкретным.

В колонке Type помечаю реальный жанр страницы (даже если она «mixed» — смешанная). Mixed-страницы — главные кандидаты на разделение.

Целевая структура

После аудита проектируется целевая структура. Корневая навигация — четыре раздела:

docs/
├── tutorials/
│   ├── getting-started.md
│   ├── deploy-first-app.md
│   └── ...
├── how-to/
│   ├── configure-cors.md
│   ├── add-caching.md
│   └── ...
├── reference/
│   ├── api/                  # generated
│   │   └── ...
│   ├── configuration.md
│   └── cli.md
└── explanation/
    ├── architecture.md
    ├── cache-invalidation.md
    └── ...

Каждый файл — один жанр. Если страница совмещает два — её делят на две.

Это идеал. К нему движутся постепенно, не за один спринт.

Миграция: что делать первым

Не перепиши всё за неделю. Иначе результат — это полупереписанная документация, в которой одни страницы по новой структуре, другие по старой, навигация запутанная, читателю хуже, чем было.

Рабочий порядок:

Создать четыре пустых раздела в новой навигации.
Перенести самые важные страницы (топ-5 по трафику) в правильный раздел. Не переписывать, просто переместить.
На главной странице — добавить ссылки на четыре раздела, объяснить, кто что найдёт где.
На существующих страницах поставить лейблы: «This page will be reorganized into Tutorials» — так читатель видит работу.
По одному жанру за раз: сначала навести порядок в Tutorials, потом в How-to, потом в Reference, потом в Explanation.

На больших проектах миграция занимает 3-6 месяцев в фоне.

Что чаще всего идёт не так

Слишком много жанров. «Добавим ещё Glossary, FAQ, Cookbook, Recipes, Best Practices...». Diátaxis — четыре жанра, не больше. Cookbook — это how-to. FAQ — обычно куски how-to и explanation, рассованные по вопросам.

Reference, в котором примеры getting started. Reference должен быть строгим: имя, сигнатура, параметры, возврат, пример. Не туториал внутри.

Explanation, который никто не читает. Если страница архитектуры за полгода открывалась 12 раз, она не нужна. Отдай в архив.

How-to, который начинается с «Установите Node.js». Это туториал. How-to начинается с предположения, что читатель уже умеет.

Один туториал «Полный гайд по нашему продукту». Если туториал длиннее часа — это не туториал. Разбей на части по конкретным целям.

Reference: автоматизация

Reference — единственный жанр, который должен быть сгенерирован из кода, насколько возможно.

API библиотеки — TypeDoc, Sphinx, godoc, javadoc.
HTTP API — OpenAPI с рендером через Redoc или Swagger UI.
CLI — генератор из кода (cobra для Go, click для Python имеют автодоки).
Конфигурационные файлы — генератор из JSON Schema или подобного.

Reference, написанный руками, расходится с кодом за пару месяцев. Если в команде нет ресурсов на синхронизацию — лучше его вообще не иметь, чем иметь устаревший. Читатели быстро привыкают «не доверять reference, идти в код».

How-to: как находить кандидатов

How-to чаще всего не пишут вовремя. Они появляются как ответы на вопросы в Slack, потом теряются.

Источники how-to:

Часто задаваемые вопросы в support-чате.
Issues с лейблом «question» в трекере.
Постмортемы инцидентов — «как избежать в следующий раз».
Внутренние playbook-и, которыми пользуется команда.

Я раз в месяц прохожу по support-чату за месяц, выписываю топ-5 вопросов, и из тех, на которые отвечали более одного раза, делаю how-to. Это самый частый паттерн «новой страницы» в Diátaxis-документации.

Tutorials: как не сделать слишком длинный

Хороший туториал — 30-60 минут на прохождение. Если дольше — читатель не закончит. Если меньше — это how-to.

Признаки, что туториал слишком длинный:

Есть пункты типа «А теперь добавим аутентификацию», «Теперь развернём в продакшен», «И ещё интеграция с CI».
Файл больше 800 строк.
Шагов больше 20.

Решение — разбить на цепочку. Туториал A: «Build your first API». Туториал B: «Add authentication to your API» (с предположением, что A пройден). Туториал C: «Deploy your API». Каждый — отдельная цель, по 30 минут.

Explanation: что писать, а что нет

Explanation — самый соблазнительный для технических писателей жанр. Хочется объяснить всё, что знаешь. Но это путь к складу неиспользуемых страниц.

Чему стоит посвятить explanation:

Архитектурным решениям, которые не очевидны из кода. «Почему мы синхронизируем кеш через Redis, а не через postgres LISTEN/NOTIFY».
Концепциям, которые много раз приходится объяснять новым сотрудникам или клиентам.
Trade-off-ам, которые мы приняли. «Почему наш API eventually consistent, а не strongly consistent».

Чему — точно нет:

Перепересказу кода. Если можно прочитать код за 5 минут, объяснение лишнее.
Истории проекта. «Мы начали в 2022, потом перешли на TypeScript...». Это блог, не документация.
Маркетинговым текстам. «Наша архитектура передовая...». В документации это шум.

Как навигация показывает читателю, куда идти

Главная страница документации — это путеводитель. Не «Welcome to the docs», а конкретный навигатор:

# Documentation

## I want to learn — start here
- [Build your first app](/tutorials/first-app/) (30 min)
- [Deploy to production](/tutorials/deploy/) (45 min)

## I want to do something specific
- [Configure CORS](/how-to/cors/)
- [Add caching layer](/how-to/caching/)
- [Migrate from v2 to v3](/how-to/migrate-v3/)

## I need to look something up
- [HTTP API Reference](/reference/api/)
- [Configuration options](/reference/config/)
- [CLI commands](/reference/cli/)

## I want to understand how it works
- [Architecture overview](/explanation/architecture/)
- [Why we chose Postgres](/explanation/storage-choice/)

Заголовки разделов — от лица читателя. Не «Tutorials», «How-to», «Reference», «Explanation» (хотя URL могут быть такими), а «I want to learn», «I want to do», «I need to look up», «I want to understand». Читатель сразу видит, куда ему идти.

Метрики, что Diátaxis работает

После внедрения стоит проверить, что становится лучше. Что мерить:

Время от первого открытия документации до первого «hello world». Должно сокращаться благодаря явным туториалам.
Распределение трафика по разделам. Не все 100% на Reference (значит, остальные жанры не нашлись).
Количество вопросов в support, которые гуглятся в документации. Если те же вопросы повторяются — нужного how-to нет.
Bounce rate на главной странице. Если читатели не находят, куда идти, — навигация не работает.

Чек-лист внедрения

Аудит текущей документации с пометкой жанра каждой страницы.
Список mixed-страниц, которые нужно разделить.
Целевая структура папок: 4 раздела по жанрам.
Главная страница с навигацией от лица читателя.
Reference генерируется из кода, не пишется руками.
Tutorials по 30-60 минут, не дольше.
How-to пишутся как ответы на повторяющиеся вопросы.
Explanation — только про неочевидные решения.
Каждая страница — один жанр.
В CI или ревью кто-то следит, чтобы новые страницы не смешивали жанры.

Diátaxis — это не магическая формула, после которой документация сама становится хорошей. Это инструмент разделения, который снимает один из самых частых провалов: смесь жанров на одной странице. Когда жанры разделены, каждый делает свою работу, и документация перестаёт быть «свалкой полезного». Внедрять долго, но окупается на горизонте полугода.