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

Четыре типа документов — не путайте их между собой

Есть классическая модель. Вся документация делится на четыре типа, и каждый решает свою задачу:

Обучающие материалы (уроки). Для тех, кто первый раз в руки взял ваш продукт. Задача — провести за руку от нуля до работающего результата. «Сделайте это → теперь это → вот, работает». Без лишних объяснений и без альтернативных путей.

Ошибка: писать в уроке «вы также можете использовать вариант Б» — человек запутается. В уроке — только один путь.

Практические руководства. Для тех, кто уже освоился и хочет решить конкретную задачу. «Как настроить уведомления по почте», «Как подключить платёжную систему». Отличие от урока: руководство предполагает, что читатель понимает основы. Можно упоминать варианты, оговорки, особые случаи.

Справочник. Сухое описание всего, что есть: параметры функций, коды ошибок, форматы данных. Справочник не учит — он отвечает на вопрос «какие аргументы принимает эта функция?». Полнота важнее читаемости. Справочник можно генерировать автоматически из кода — и это нормально.

Объяснения (концепции). Ответ на вопрос «почему?». Почему архитектура устроена так, а не иначе. Почему выбрали такой формат данных. Какие компромиссы стоят за решениями. Это не пошаговая инструкция и не справочник — это контекст для принятия решений.

Главное правило: не мешать типы в одном документе. Урок с вставками из справочника — плохой урок. Справочник с длинными объяснениями «почему» — плохой справочник. Каждый документ должен делать одно дело.

Первые пять минут решают всё

Что должно быть на первой странице документации:

Одно предложение — что делает продукт. Не миссия компании, не «мы переизобретаем взаимодействие», а конкретно: «Сервис для отправки СМС через программный интерфейс» или «Библиотека для работы с временными рядами в Питоне».

Готовый пример, который можно скопировать и запустить. Не «концептуальный пример», а рабочий. С тестовыми ключами, которые работают сразу после регистрации. Или вообще без регистрации — через песочницу.

Понятная последовательность: зарегистрироваться → получить ключ → скопировать пример → запустить → увидеть результат. Каждый шаг — со ссылкой туда, где это делается.

Примеры кода: семь правил

Примеры кода — основа документации для разработчиков. Плохие примеры убивают хорошую документацию. Вот что отличает рабочий пример от бесполезного:

Пример должен быть полным. Не «тут используйте функцию X(params)» — а полный рабочий файл, который можно скопировать, сохранить и запустить. Со всеми подключениями, со всеми настройками, со значениями переменных.

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

Используйте реалистичные данные. Не foo, bar, test123. А user@example.com, order_id: "ord_8K2mPxNvLw", amount: 1500. Реалистичные данные помогают понять, что куда подставлять.

Показывайте результат. После примера кода — что выведет программа. Какой ответ вернёт сервер. Как будет выглядеть результат. Разработчик должен понимать, чего ожидать, чтобы сравнить со своим результатом.

Подписывайте важные строки.

Примеры на нескольких языках.

Ошибки и их описания

Разработчик получает ошибку от вашего продукта — и что он видит?

Плохо: Error 4012 Чуть лучше: Error 4012: Invalid request Нормально: Error 4012: Invalid request — the "amount" field must be a positive integer, got string "abc" Хорошо: Error 4012: Invalid request — the "amount" field must be a positive integer, got string "abc". See https://docs.example.com/errors/222

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

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

Поддерживайте документацию как код

Документация устаревает. Продукт обновился, а примеры — нет. Добавили новый параметр, а в справочнике его нет. Убрали старый способ авторизации, а в уроке он всё ещё описан.

Решение — относиться к документации как к коду:

Хранить в том же репозитории, что и продукт. Обновления документации — часть задачи на изменение продукта. Нельзя выпустить новую версию без обновления документации (как нельзя выпустить без тестов).

Автоматически проверять примеры кода. Есть инструменты, которые запускают примеры из документации при сборке и проверяют, что они работают. Если пример сломался — сборка не пройдёт.

Рецензировать изменения документации так же, как рецензируете код. Кто-то добавил новый раздел — второй человек читает и проверяет, понятно ли написано.

Не пишите «просто»

«Просто добавьте ключ в заголовок запроса». Просто? А если человек не знает, что такое заголовок запроса? Или не знает, как его добавить в своём языке? «Просто» — это обесценивание сложности. Уберите это слово из документации целиком, и текст станет лучше.

То же касается «очевидно», «легко», «всего лишь». Если бы это было очевидно — человек не читал бы документацию.

Обратная связь

Хорошая документация улучшается, когда разработчики сообщают, что непонятно.

Минимально: кнопка «Было ли это полезно?» на каждой странице. Даёт грубый сигнал, но лучше, чем ничего.

Лучше: возможность предложить исправление прямо на странице (ссылка «Редактировать на Гитхабе»). Разработчики — щедрые люди. Если они нашли ошибку и им легко её исправить — многие исправят.

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

Итого

Хорошая документация для разработчиков — не пдф на 500 страниц. Это четыре типа документов, каждый для своей цели. Быстрый старт, который работает за пять минут. Примеры кода, которые можно скопировать и запустить. Понятные ошибки со ссылками на решения. И процесс, который поддерживает всё это в актуальном состоянии.

Хорошая документация редко существует отдельно от среды, в которой разработчикам вообще хочется читать, разбираться и доверять. На курсе «Специалист по работе с ИТ сообществом/DevRel» разбирают, как строить такую среду на практике: через стратегию бренда работодателя, технический контент, сообщества, мероприятия и работу с экспертами внутри компании.

Чтобы узнать больше о формате обучения и познакомиться с преподавателями, приходите на бесплатный урок курса, который пройдет 18 марта в 20:00. Поговорим о том, как DevRel-инструменты и сообщества становятся «фабрикой талантов» внутри компании, снижая затраты и повышая устойчивость бизнеса. Записаться на урок

Еще больше бесплатных уроков от преподавателей курсов по всем ИТ-направлениям можно посмотреть в календаре мероприятий.