Документация для junior и senior: как писать одну, чтобы работала для обоих

Документация про API часто пишется с прицелом «для разработчика». Что это значит на практике — никто не уточняет. И один и тот же текст оказывается одновременно слишком подробным для опытных и слишком скупым для тех, кто видит API впервые. Опытные раздражаются «зачем мне эти десять шагов установки», новички теряются «откуда мне взять токен».

Документация — это разговор с конкретным читателем. У junior и senior разные задачи, разный объём знаний и разный темп. Один документ для обоих почти всегда работает плохо. Разберу, как структурировать документацию так, чтобы и тот и другой нашли своё, и где начинается перебор «двух разных доков».

Чем отличаются ожидания

Junior-разработчик, читающий документацию, обычно:

• Не знает, как устроен ваш API в целом. Нужен обзор и точка входа.
• Не знает, какие термины — стандартные, а какие — ваши собственные. Нужны определения.
• Боится сделать что-то «не так» в проде. Нужны явные предупреждения.
• Хочет рабочий пример, который запускается без модификаций.
• Не разбирается, какой из вариантов выбрать. Нужны рекомендации.

Senior-разработчик, читающий ту же документацию:

• Знает паттерны, ему не нужны объяснения, что такое REST или JWT.
• Ищет конкретный параметр, эндпоинт, формат ответа.
• Просматривает страницу за 10 секунд, не читая абзацы целиком.
• Раздражается на лишние предупреждения и уговоры.
• Знает, какие альтернативы рассматривать, и принимает выбор сам.

Если документация написана с фокусом на одну группу — другая страдает.

Что не стоит делать

Один длинный документ для всех. Внутри начинаются развилки: «если вы новичок, начните отсюда; если опытный, перейдите вниз». Получается смесь, в которой каждый читатель пропускает половину, и эта половина может содержать критичную деталь.

Две полностью разделённых документации. «Beginner Guide» и «Advanced Reference» как два сайта. Дублирование, расхождение через полгода, сложность поддержки.

Уровни сложности на каждой странице. «Basic», «Intermediate», «Advanced» как табы. Усложнение навигации без выгоды — junior не знает, какой уровень его, senior раздражается на лишние клики.

Что стоит делать: разделение по жанрам

Решение — не два разных сайта, а структура, в которой каждый жанр естественно подходит своему читателю.

Возвращаясь к Diátaxis:

• Tutorials — для junior. Пошаговые сценарии с объяснениями.
• How-to guides — для middle/senior. Конкретные задачи, без обучения.
• Reference — для всех. Машинно-сгенерированный, исчерпывающий.
• Explanation — для тех, кто хочет глубже. Часто senior.

Junior начинает с tutorials, оттуда плавно переходит в how-to и reference по мере роста. Senior сразу прыгает в reference, иногда заходит в how-to для нестандартного. Один и тот же материал не дублируется — он живёт в одном жанре, но соответствующем читателю.

Tutorial для junior: что обязательно

Туториал, который реально помогает новичку, должен включать:

• Определение терминов при первом упоминании. «JWT (JSON Web Token) — это токен в формате...». Не вставляй ссылку на википедию, дай короткое определение в одно предложение.
• Шаги в строгом порядке, без выбора. Не «можно использовать SQLite или Postgres» — выбери один, и дай его. Альтернативы — в отдельном how-to.
• Промежуточные результаты. «После этого шага запустите команду X, увидите такой вывод». Junior нуждается в подтверждении, что движется правильно.
• Ошибки и что делать. «Если получили Connection refused, проверьте порт». Самые частые проблемы — заранее.
• Полный рабочий код в конце. Чтобы можно было сравнить со своим.

Длинный туториал, в котором всё это есть, — нормально для junior. Senior туда не пойдёт, и не должен.

How-to для middle/senior: что обязательно

How-to — это инструкция «как сделать конкретное», предполагающая, что читатель уже умеет.

• Заголовок — задача. «Configure CORS», не «CORS configuration explained».
• Никаких длинных вступлений. Сразу к решению.
• Один сценарий. «Add caching with Redis», не «Add caching with various backends».
• Минимум фоновой информации. Если нужно объяснить концепцию — ссылка на explanation.
• Готовое решение в коде. Скопировать, адаптировать, готово.

How-to обычно короткие — 1-3 экрана. Если длиннее, это уже туториал или explanation.

Reference: одинаковый для всех

Reference — самый универсальный жанр. И junior, и senior смотрят туда одинаково: «какие параметры», «какой формат ответа», «какие коды ошибок».

Что важно в reference для всех:

• Машинно-сгенерированный из кода. Любая ручная синхронизация устаревает.
• Полный. Все эндпоинты, все параметры, все ошибки.
• Структурированный. Одинаковая структура у всех страниц.
• Без вступительных текстов. Никаких «Эта функция позволяет вам...».

Reference не делается «для junior» или «для senior». Он делается для всех, и всем удобен.

Edge cases: где разделение оправдано

Иногда разделение по уровню всё-таки нужно. Конкретные сценарии:

Onboarding-документация для команды. Это туториалы плюс набор how-to для типичных задач. Senior, придя в новую команду, тоже её читает — но быстро. Junior на старте — медленно. Дублирование не нужно.

Документация по фреймворку для junior-developer-ов. Если фреймворк ориентирован именно на новичков (например, обучающие платформы), весь стиль документации — туториальный. Это нишевый случай.

Migration guide. Гайд миграции с одной версии на другую — это отдельный жанр, обычно для senior. Junior на новом проекте сразу пишет под актуальной версией, ему не нужно.

Tone и язык

Тон в документации часто страдает крайностями. Либо слишком фамильярный («Привет! Сегодня мы научимся...»), либо слишком официальный («Настоящее руководство описывает...»).

Что работает для всех:

• Простой язык. Короткие предложения.
• Прямое обращение «вы» или «ты», но не «мы». «Создайте файл», не «Создаём файл».
• Без покровительственных слов: «просто», «легко», «очевидно». Junior читает «легко» и думает «у меня не получается, я тупой». Senior читает и пропускает.
• Без избыточной вежливости в reference. «Please specify the host» — лишнее, «Specify the host» — точнее.

Тон туториала чуть теплее (направляет читателя), тон reference нейтральный (просто описывает). Тон how-to — между ними.

Где не нужны предупреждения, а где нужны

«Будьте осторожны при использовании этой функции» — самое частое раздражение senior. Если предупреждение оправдано (deletion без подтверждения, breaking effect), оно нужно. Если просто «обратите внимание, что эта функция мутирует объект» — это в reference, не в виде admonition.

Хорошие предупреждения:

• «Этот эндпоинт удаляет данные без возможности восстановления».
• «В прод не запускайте до полного аудита прав».
• «Тайм-аут — 30 секунд, после чего соединение разрывается».

Плохие предупреждения:

• «Будьте внимательны при работе с этой функцией».
• «Рекомендуется использовать осторожно».
• «Этот метод предназначен для опытных пользователей».

Первая группа — конкретный риск с инструкцией. Вторая — пугание без действия.

Поиск и навигация

Поиск — главный инструмент senior. Они вбивают «error 401», ожидают увидеть страницу про этот код. Если поиск плохой, senior уходит в код.

Главная страница — главный инструмент junior. Они приходят впервые, не знают, что искать. На главной должны быть: «I want to start», «I want to do X», «I want to look up Y», «I want to understand».

Если на главной — длинное описание продукта и philosophy, junior уходит, не найдя «как начать».

Чек-лист, что документация работает для обоих

• Есть туториалы с пошаговым обучением, ориентированы на junior.
• Есть how-to для конкретных задач, без обучения, для middle/senior.
• Reference сгенерирован из кода, полный и одинаковый для всех.
• На главной странице — навигация по задачам, а не по продукту.
• Поиск работает на всех страницах.
• В туториалах объясняются термины при первом упоминании.
• В how-to — никаких объяснений, только действия.
• Тон везде нейтральный, без покровительства.
• Предупреждения — только конкретные риски с инструкцией.
• Нет дублирования между «версиями для разных уровней».

Ошибки, на которые натыкаются команды

«Доку для senior напишут разработчики, доку для junior — технический писатель». Это разделение труда — иллюзия. Reference пишут разработчики (или генератор из их docstring). Туториалы и how-to — совместная работа писателя и разработчика. Если их разделить — оба продукта получаются хуже.

«Senior не нужна документация, они и так разберутся». Senior нужна — но другая. Reference, list of options, edge cases. Если этого нет, senior разбирается через чтение кода и тратит больше времени, чем junior на туториал.

«Junior — это временная категория, пусть страдают, потом станут senior». Junior сегодня — senior через два года. Если они уходят, не закрепившись в продукте, рынка не остаётся. Документация для junior — инвестиция в собственное будущее.

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