Туториалы vs reference: как разделить два жанра в документации

17 мая 2026 г. 10K

Документация на проекте есть, но люди всё равно пишут в саппорт «как сделать X?». Открываешь страницу — там дана функция doX(opts) с типизацией параметров и описанием каждого поля. Формально полная информация. Но человек не может понять, в каком порядке вызывать эти функции, какой минимальный сценарий, что из этого критично.

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

Кому это нужно знать

Подход разделять документацию по жанрам формализован в Diátaxis: четыре типа документов под четыре потребности — туториал, how-to, reference, explanation. На практике большинство команд начинают с двух самых заметных: туториалов и reference. Остальные жанры приходят позже, когда видно, что без них чего-то не хватает.

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

Туториал: что это и для кого

Туториал — это пошаговый сценарий, который ведёт читателя от нуля к работающему результату. Цель — обучить, а не описать. Читатель — новичок, он не знает доменного языка, не знает терминов библиотеки, не знает, в каком порядке что вызывать.

Признаки хорошего туториала:

Есть конкретная цель: «к концу туториала вы получите работающий сервер с auth-эндпоинтом».
Шаги в строгом порядке. Невозможно прочитать через один и получить результат.
Каждый шаг приводит к видимому промежуточному результату («запустите команду — увидите такой вывод»).
Минимум выбора. Не «можно использовать A, B или C» — только «делаем A».
Результат проверяем: к концу — работающий код, который можно открыть и запустить.

Туториал — не место для полноты. Не нужно перечислять все опции, все альтернативы, все edge case-ы. Это снижает когнитивную нагрузку и уводит от главной цели.

Reference: что это и для кого

Reference — это исчерпывающее описание API. Цель — отвечать на конкретные вопросы. Читатель — уже знает, что ищет: «какие опции у функции foo», «какие поля в ответе /users», «какие коды ошибок возвращает POST /transfer».

Признаки хорошего reference:

Полный. Описаны все публичные функции, эндпоинты, параметры, поля.
Систематичный. Одинаковая структура для всех страниц: имя, сигнатура, параметры, возврат, примеры, исключения.
Точный. Если параметр опциональный — это указано. Если default есть — значение указано. Если поле может быть null — это указано.
Машинно-сгенерированный, насколько возможно. Reference расходится с кодом, если его пишут руками.
Без обучения. В reference нет «начнём с установки, потом посмотрим...». Только структура и факты.

Как читатель попадает к каждому жанру

Туториал — целенаправленно, с навигации «Getting Started» на главной странице доки. Человек открывает доку, ищет «как начать», попадает в туториал.

Reference — через поиск или через ссылку из туториала/руководства. Никто не читает reference сверху вниз. Заходят, ищут конкретное, читают одну страницу, уходят.

Из этого следует разная поисковая оптимизация. Заголовок туториала — «Build a REST API with FastAPI». Заголовок reference-страницы — точный идентификатор: «FastAPI.add_middleware». Первое отвечает на «как сделать», второе — на «что это такое».

Что ломается, когда жанры смешаны

Самые частые провалы:

«Туториал», в котором перечисляются все опции каждой функции. Читатель тонет в деталях, не доходит до результата.
«Reference», где у каждой функции пример из getting started. Reference распухает, повторы становятся главным шумом.
«Туториал», в котором три варианта на каждом шаге. «Можно использовать SQLite или Postgres, выберите...» — выбор ломает поток обучения.
«Reference», написанный прозой. «Эта функция позволяет...» вместо строгой структуры. Читать долго, найти трудно.

Когда документация смешивает жанры, видно по реакции читателей. Они либо «не могут начать» (туториал не работает как туториал), либо «не могут найти параметр» (reference не работает как reference). Решение — разнести на разные страницы, со своими правилами и шаблонами.

Структура туториала

Шаблон, который у меня работает на разных проектах:

Что вы получите. 1-2 предложения и скриншот/код результата. Без воды.
Что нужно знать заранее. Список prerequisite. Чётко: «Python 3.11+, базовое знание HTTP-методов».
Установка. Одна команда, без вариантов.
Шаги. Заголовок шага — действие. Тело шага — кусочек кода + краткое объяснение, зачем это делаем.
Проверка. «Запустите npm test, увидите такой вывод» — подтверждение, что всё получилось.
Что дальше. Ссылки на 2-3 связанных how-to или продвинутых туториала. Не на reference и не на explanation.

Структура reference-страницы

Шаблон под одну функцию или эндпоинт:

## `createUser(data, options?)`

Создаёт пользователя.

**Signature**

`function createUser(data: UserData, options?: CreateOptions): Promise<User>`

**Parameters**

- `data` (`UserData`, required) — данные пользователя.
  - `data.email` (`string`, required) — email, валидируется по RFC 5322.
  - `data.name` (`string`, required) — имя, 1-100 символов.
  - `data.role` (`'admin' | 'user'`, optional) — роль, по умолчанию `'user'`.
- `options` (`CreateOptions`, optional) — настройки.
  - `options.notify` (`boolean`, optional) — отправить welcome email, по умолчанию `false`.

**Returns**

`Promise<User>` — созданный пользователь с заполненным `id` и `created_at`.

**Throws**

- `ValidationError` — невалидные `data.email` или `data.name`.
- `ConflictError` — email уже зарегистрирован.

**Example**

`const user = await createUser({ email: 'a@b.c', name: 'A' })`

Структура одинаковая для всех функций. Это позволяет читателю scan-ить страницу: видишь заголовок, прыгаешь в Parameters, находишь нужное поле, смотришь тип и default. Без прозы.

Когда нужно одно, когда другое

Конкретные сценарии:

Туториал:

«Как сделать первое приложение с библиотекой X».
«Как развернуть проект на сервере, шаг за шагом».
«Как пройти от нуля до работающего CI».

Reference:

«Список всех HTTP-эндпоинтов с параметрами».
«API классов и функций библиотеки».
«Список всех опций конфигурации с дефолтами».
«Описание схемы данных, всех полей таблиц».

Если документ начинается со слов «Полный справочник по...» или «Все функции класса...» — это reference. Если начинается с «Шаг 1...» или «Создадим...» — это туториал.

How-to и explanation: между туториалом и reference

Если жанры туториал и reference покрыли половину вопросов — оставшиеся требуют ещё двух типов:

How-to — ответы на «как сделать конкретную задачу», когда читатель уже знает основы. «Как настроить CORS», «Как добавить кеш для Postgres-запросов». Туториал учит с нуля, how-to отвечает на конкретный вопрос.

Отличие в фокусе: how-to не идёт от нуля, не учит концепциям, а предполагает, что читатель знает базу. Структура — задача, шаги, готово. Без длинных объяснений.

Explanation — пояснения концепций, архитектуры, design decisions. «Как работает наш кеш-инвалидатор», «Почему мы выбрали такую схему транзакций», «Что такое event sourcing в нашем контексте».

Это самый редкий жанр в документации проектов: нет прямого практического применения, читатель — тот, кто хочет глубже понять. Часто живёт как ADR или design doc, не на главных страницах сайта.

Навигация: куда читатель идёт

Если документация структурирована по жанрам, навигация выглядит так:

- Tutorials (для новичков)
  - Build your first API
  - Deploy to production
- How-to guides (для конкретных задач)
  - Configure CORS
  - Add caching layer
  - Migrate from v2 to v3
- Reference (для уточнений)
  - HTTP API
  - SDK API
  - Configuration options
- Explanation (для понимания)
  - Architecture overview
  - Concurrency model
  - Why we chose Postgres

Навигация говорит читателю, где искать. «У меня нет времени, я просто хочу настроить CORS» — идёт в How-to. «Я только что узнал про библиотеку и хочу попробовать» — идёт в Tutorials. «Знаю всё, забыл сигнатуру функции» — идёт в Reference.

Антипаттерны

Когда жанры разделены, начинаются другие проблемы:

Туториал, в котором не работает код. Так как примеры не проверяются, через полгода они расходятся с реальностью. Решение — туториальный код в репозитории, прогон в CI.
Reference, не собранный из кода. Через полгода «параметр flush» исчез из кода, в reference остался. Решение — собирать reference из docstring/JSDoc/OpenAPI.
How-to с непроверяемыми условиями. «Если у вас Linux 5.x...» — превращается в swamp вариантов. Решение — выделять конкретные сценарии в отдельные how-to.
Explanation, который никто не читает. Если ради одной страницы про concurrency model никто не приходит — может, его и не нужно. Не пишем впрок.

Как переезжать на разделение жанров

Команды, у которых документация — это «один большой README» или Wiki со смешанными страницами, обычно боятся переезжать. Боятся, что переписывать всё.

Рабочий план:

Один туториал, один reference. Не больше для начала.
Туториал — самый частый сценарий «getting started». Пишется руками, тестируется на новом сотруднике.
Reference — собирается из кода. Если в коде нет docstring/JSDoc — это первый шаг, доку без них не собрать.
По мере роста — добавляются how-to для частых задач, explanation для важных решений.

Это не «переписать всё за неделю», а постепенное наращивание. Старые страницы Wiki можно оставить как есть, новые писать по жанрам. Через год соотношение перевернётся.

Чек-лист, как понять, что у вас провал жанров

Новые сотрудники не могут «начать» по документации, ходят к старшим за подсказками.
Документация по «как сделать» спрятана внутри длинного reference.
Reference содержит примеры getting started, повторяющиеся на каждой странице.
Туториал заканчивается списком всех опций с настройками.
В навигации есть «Documentation» как одна большая папка без разделения.
Часть страниц — пошаговые, часть — справочник, всё перемешано.

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

Туториал и reference — два разных документа, у них разная структура, разные читатели, разные требования. Когда они разделены, каждый делает свою работу хорошо. Когда смешаны — никто не читает.