- Регистрация
- 23 Авг 2023
- Сообщения
- 3,969
- Реакции
- 0
- Баллы
- 36
Ofline
Большинство документаций к продуктам для разработчиков — плохие. Не потому что авторы не старались, а потому что документацию писал инженер, который знает продукт насквозь, и ему «всё очевидно». А человеку, который видит продукт впервые, — ничего не очевидно.
Есть классическая модель. Вся документация делится на четыре типа, и каждый решает свою задачу:
Обучающие материалы (уроки). Для тех, кто первый раз в руки взял ваш продукт. Задача — провести за руку от нуля до работающего результата. «Сделайте это → теперь это → вот, работает». Без лишних объяснений и без альтернативных путей.
Ошибка: писать в уроке «вы также можете использовать вариант Б» — человек запутается. В уроке — только один путь.
Практические руководства. Для тех, кто уже освоился и хочет решить конкретную задачу. «Как настроить уведомления по почте», «Как подключить платёжную систему». Отличие от урока: руководство предполагает, что читатель понимает основы. Можно упоминать варианты, оговорки, особые случаи.
Справочник. Сухое описание всего, что есть: параметры функций, коды ошибок, форматы данных. Справочник не учит — он отвечает на вопрос «какие аргументы принимает эта функция?». Полнота важнее читаемости. Справочник можно генерировать автоматически из кода — и это нормально.
Объяснения (концепции). Ответ на вопрос «почему?». Почему архитектура устроена так, а не иначе. Почему выбрали такой формат данных. Какие компромиссы стоят за решениями. Это не пошаговая инструкция и не справочник — это контекст для принятия решений.
Главное правило: не мешать типы в одном документе. Урок с вставками из справочника — плохой урок. Справочник с длинными объяснениями «почему» — плохой справочник. Каждый документ должен делать одно дело.
Что должно быть на первой странице документации:
Одно предложение — что делает продукт. Не миссия компании, не «мы переизобретаем взаимодействие», а конкретно: «Сервис для отправки СМС через программный интерфейс» или «Библиотека для работы с временными рядами в Питоне».
Готовый пример, который можно скопировать и запустить. Не «концептуальный пример», а рабочий. С тестовыми ключами, которые работают сразу после регистрации. Или вообще без регистрации — через песочницу.
Понятная последовательность: зарегистрироваться → получить ключ → скопировать пример → запустить → увидеть результат. Каждый шаг — со ссылкой туда, где это делается.
Примеры кода — основа документации для разработчиков. Плохие примеры убивают хорошую документацию. Вот что отличает рабочий пример от бесполезного:
Пример должен быть полным. Не «тут используйте функцию X(params)» — а полный рабочий файл, который можно скопировать, сохранить и запустить. Со всеми подключениями, со всеми настройками, со значениями переменных.
Пример должен быть минимальным. Только то, что нужно для демонстрации конкретной функции. Не тащите в пример обработку ошибок, логирование и конфигурацию, если статья — про отправку запроса. Покажите суть. Дополнительные вещи — в отдельных разделах.
Используйте реалистичные данные. Не
Показывайте результат. После примера кода — что выведет программа. Какой ответ вернёт сервер. Как будет выглядеть результат. Разработчик должен понимать, чего ожидать, чтобы сравнить со своим результатом.
Подписывайте важные строки.
Примеры на нескольких языках.
Разработчик получает ошибку от вашего продукта — и что он видит?
Плохо:
Каждая ошибка должна: назвать себя понятно, объяснить что пошло не так, подсказать как починить. Ссылка на документацию — лучший вариант, потому что в тексте ошибки не всегда уместно писать длинное объяснение.
Заведите страницу с описанием всех кодов ошибок. Это один из самых посещаемых разделов документации — разработчики приходят туда, когда что-то сломалось, и им нужен ответ прямо сейчас.
Документация устаревает. Продукт обновился, а примеры — нет. Добавили новый параметр, а в справочнике его нет. Убрали старый способ авторизации, а в уроке он всё ещё описан.
Решение — относиться к документации как к коду:
Хранить в том же репозитории, что и продукт. Обновления документации — часть задачи на изменение продукта. Нельзя выпустить новую версию без обновления документации (как нельзя выпустить без тестов).
Автоматически проверять примеры кода. Есть инструменты, которые запускают примеры из документации при сборке и проверяют, что они работают. Если пример сломался — сборка не пройдёт.
Рецензировать изменения документации так же, как рецензируете код. Кто-то добавил новый раздел — второй человек читает и проверяет, понятно ли написано.
«Просто добавьте ключ в заголовок запроса». Просто? А если человек не знает, что такое заголовок запроса? Или не знает, как его добавить в своём языке? «Просто» — это обесценивание сложности. Уберите это слово из документации целиком, и текст станет лучше.
То же касается «очевидно», «легко», «всего лишь». Если бы это было очевидно — человек не читал бы документацию.
Хорошая документация улучшается, когда разработчики сообщают, что непонятно.
Минимально: кнопка «Было ли это полезно?» на каждой странице. Даёт грубый сигнал, но лучше, чем ничего.
Лучше: возможность предложить исправление прямо на странице (ссылка «Редактировать на Гитхабе»). Разработчики — щедрые люди. Если они нашли ошибку и им легко её исправить — многие исправят.
Ещё лучше: читать вопросы в сообществе, на форумах, в чатах поддержки. Каждый повторяющийся вопрос — это дырка в документации. Закройте дырку — и вопрос перестанет повторяться.
Хорошая документация для разработчиков — не пдф на 500 страниц. Это четыре типа документов, каждый для своей цели. Быстрый старт, который работает за пять минут. Примеры кода, которые можно скопировать и запустить. Понятные ошибки со ссылками на решения. И процесс, который поддерживает всё это в актуальном состоянии.
Хорошая документация редко существует отдельно от среды, в которой разработчикам вообще хочется читать, разбираться и доверять. На курсе «Специалист по работе с ИТ сообществом/DevRel» разбирают, как строить такую среду на практике: через стратегию бренда работодателя, технический контент, сообщества, мероприятия и работу с экспертами внутри компании.
Чтобы узнать больше о формате обучения и познакомиться с преподавателями, приходите на бесплатный урок курса, который пройдет 18 марта в 20:00. Поговорим о том, как DevRel-инструменты и сообщества становятся «фабрикой талантов» внутри компании, снижая затраты и повышая устойчивость бизнеса. Записаться на урок
Еще больше бесплатных уроков от преподавателей курсов по всем ИТ-направлениям можно посмотреть в календаре мероприятий.
Четыре типа документов — не путайте их между собой
Есть классическая модель. Вся документация делится на четыре типа, и каждый решает свою задачу:
Обучающие материалы (уроки). Для тех, кто первый раз в руки взял ваш продукт. Задача — провести за руку от нуля до работающего результата. «Сделайте это → теперь это → вот, работает». Без лишних объяснений и без альтернативных путей.
Ошибка: писать в уроке «вы также можете использовать вариант Б» — человек запутается. В уроке — только один путь.
Практические руководства. Для тех, кто уже освоился и хочет решить конкретную задачу. «Как настроить уведомления по почте», «Как подключить платёжную систему». Отличие от урока: руководство предполагает, что читатель понимает основы. Можно упоминать варианты, оговорки, особые случаи.
Справочник. Сухое описание всего, что есть: параметры функций, коды ошибок, форматы данных. Справочник не учит — он отвечает на вопрос «какие аргументы принимает эта функция?». Полнота важнее читаемости. Справочник можно генерировать автоматически из кода — и это нормально.
Объяснения (концепции). Ответ на вопрос «почему?». Почему архитектура устроена так, а не иначе. Почему выбрали такой формат данных. Какие компромиссы стоят за решениями. Это не пошаговая инструкция и не справочник — это контекст для принятия решений.
Главное правило: не мешать типы в одном документе. Урок с вставками из справочника — плохой урок. Справочник с длинными объяснениями «почему» — плохой справочник. Каждый документ должен делать одно дело.
Первые пять минут решают всё
Что должно быть на первой странице документации:
Одно предложение — что делает продукт. Не миссия компании, не «мы переизобретаем взаимодействие», а конкретно: «Сервис для отправки СМС через программный интерфейс» или «Библиотека для работы с временными рядами в Питоне».
Готовый пример, который можно скопировать и запустить. Не «концептуальный пример», а рабочий. С тестовыми ключами, которые работают сразу после регистрации. Или вообще без регистрации — через песочницу.
Понятная последовательность: зарегистрироваться → получить ключ → скопировать пример → запустить → увидеть результат. Каждый шаг — со ссылкой туда, где это делается.
Примеры кода: семь правил
Примеры кода — основа документации для разработчиков. Плохие примеры убивают хорошую документацию. Вот что отличает рабочий пример от бесполезного:
Пример должен быть полным. Не «тут используйте функцию 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-инструменты и сообщества становятся «фабрикой талантов» внутри компании, снижая затраты и повышая устойчивость бизнеса. Записаться на урок
Еще больше бесплатных уроков от преподавателей курсов по всем ИТ-направлениям можно посмотреть в календаре мероприятий.