Видео по документации API, которые разработчики действительно смотрят

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

Именно этот пробел закрывает короткое видео. Оно не заменяет справочник, а дополняет его. Три минуты с настоящим ключом, настоящим запросом и настоящим ответом отвечают на вопрос, который справочнику недоступен: работает ли это так, как я думаю?

Вот как записывать такие ролики, чтобы они оставались полезными.

Решите, что заслуживает видео

Видео дорого поддерживать. Тратьте его там, где текст слабее всего:

• Первый успешный вызов: от пустого терминала до ответа 200. Самое ценное видео, которое вы можете снять
• Сценарии аутентификации: редиректы OAuth, обмен токенов и логика обновления — это последовательности. Видео создано как раз для последовательностей
• Многошаговые сценарии: создать ресурс, опросить статус, забрать результат. В справочнике это выглядит как три несвязанных эндпоинта
• Вебхуки и колбэки: диалог двух систем действительно трудно описать прозой
• Типичные ошибки: ролик про 401 и его исправление снимает больше обращений в поддержку, чем любой абзац об этом

Что не заслуживает видео: параметры отдельных эндпоинтов, значения перечислений, цифры лимитов. Им место в тексте, где их можно искать, копировать и править за секунды.

Подготовьте песочницу для записи

Никогда не записывайте боевую среду с настоящим ключом. Соберите отдельное окружение до нажатия «Запись».

• Одноразовый аккаунт в песочнице с ключами, которые вы смените сразу после съёмки
• Заполните реалистичными данными: test_user_1 и "foo" делают демо фальшивым. Правдоподобные имена, суммы и метки времени вызывают доверие к API
• Выберите короткоживущий формат ключа, если он есть: тогда случайно попавший в кадр токен безвреден
• Проверьте окружение оболочки: вывод env и история команд утекали чаще любого фрагмента кода
• Прогрейте кеши и зависимости, чтобы не записывать установку
• Отключите уведомления — превью Slack в опубликованном видео это вполне реальный инцидент

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

Выберите подходящий режим захвата

В демо API обычно участвуют две-три поверхности: терминал, редактор, клиент вроде Postman или Insomnia и иногда браузер с панелью управления.

• Захват окна для каждой поверхности держит кадр плотным и прячет беспорядок на рабочем столе
• Если переключаться между приложениями всё же нужно, расставьте их рядом заранее и снимайте область, охватывающую оба. Alt-Tab в кадре дезориентирует
• 30 кадров в секунду достаточно для текста, а меньший FPS оставляет больше битрейта на чёткие символы
• Пишите в родном разрешении — растягивание после съёмки и даёт размытость
• Увеличьте шрифты до 18–24 pt в терминале и редакторе. То, что на мониторе кажется нелепо крупным, в видео как раз впору

Стройте все ролики одинаково

Именно единообразие превращает набор скринкастов в документацию. Надёжная схема из четырёх шагов:

1. Сформулируйте цель одной фразой: «Создадим клиента и спишем с него платёж».
2. Покажите аутентификацию: даже если это один заголовок. Зрителю нужно увидеть, куда кладётся ключ
3. Соберите запрос вживую: наберите или вставьте его и пройдитесь по каждому полю. Объясните, зачем нужен каждый параметр
4. Прочитайте ответ вслух: остановитесь на JSON. Укажите поле, которое понадобится дальше

Заканчивайте анонсом: «Этот id мы используем для платежа — об этом следующий ролик».

Сделайте JSON и код читаемыми

Именно здесь проваливается большинство видео про API. Запрос прошёл, ответ заполнил экран, и зритель видит нечитаемую стену фигурных скобок.

• Форматируйте весь вывод: прогоняйте через jq или включите форматирование в клиенте
• Сворачивайте лишнее: почти любой API-клиент умеет сворачивать блоки. Сверните метаданные, которые никому не нужны
• Приближайте ключевое поле: зум на две важные строки полезнее любого пояснения. В Recorded зум добавляется потом, в редакторе, — во время записи можно сосредоточиться на самих запросах
• Подпишите поле текстом поверх кадра: метка, указывающая на subscription_status, читается быстрее, чем произносится
• Вырезайте ожидание: сетевые задержки, циклы опроса и пересборки — мёртвое время. Вырежьте их, а прошедшее время покажите короткой подписью

Говорите как коллега, а не как спецификация

Формальное описание уже есть в справочнике. Закадровый голос должен сказать то, чего документация сказать не может:

• «Вот про этот заголовок все и забывают».
• «Да, это поле обязательное, хотя выглядит необязательным».
• «Если здесь прилетает 422, почти всегда дело в формате даты».

Такие комментарии и есть настоящий продукт документального видео. Запишите три-четыре такие фразы заранее: за набором команд их легко забыть.

Держите ролики короткими и модульными

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

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

Заложите изменения API заранее

Видеодокументация устаревает быстрее текстовой. Учитывайте это с самого начала:

• Называйте версию вслух и показывайте на экране, чтобы устаревшее видео было очевидно устаревшим
• Избегайте элементов интерфейса, которые быстро стареют — редизайн панели старит ролик быстрее изменений в API
• Храните исходные записи и файлы проектов, а не только экспорт: перемонтаж не должен превращаться в пересъёмку
• Называйте файлы по эндпоинту и версии, чтобы после релиза сразу видеть, что обновлять
• Пересматривайте ролики при каждой мажорной версии и переснимайте те, что уже врут

Короткое честное видео прошлого квартала — это нормально. Уверенное видео с эндпоинтом, которого больше нет, стоит вам доверия.

Публикуйте там, где возникает вопрос

Лучше всего размещённое видео по API встроено прямо в страницу справочника этого эндпоинта, а не лежит в отдельной видеотеке, куда никто не заходит. Для роликов длиннее двух минут добавьте главы или тайм-коды, положите под плеер полный код из видео в копируемом виде, а успешный ответ экспортируйте коротким GIF для страницы быстрого старта.

Короткий чек-лист

• Аккаунт в песочнице с одноразовыми ключами
• Реалистичные тестовые данные
• Уведомления выключены, история оболочки очищена
• Шрифты увеличены, окна расставлены
• Схема: цель → аутентификация → запрос → ответ
• Отформатированный JSON, зум на ключевых полях
• Ожидание вырезано
• Версия названа на экране
• Встроено рядом с нужным разделом справочника
• Копируемый код опубликован вместе с видео

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