Видео или текст: когда записывать, а когда писать документацию

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

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

Это руководство даёт воспроизводимый способ решить за тридцать секунд, ещё до начала работы.

Тест на тридцать секунд

Задайте три вопроса о том, что вы собираетесь задокументировать.

1. Это движется? Если для понимания нужно увидеть, как что-то происходит — траекторию курсора, смену состояния, анимацию, реакцию инструмента в реальном времени, — записывайте.
2. Понадобится ли кому-то потом одна конкретная деталь? Если люди будут возвращаться, чтобы посмотреть значение, флаг или отдельный шаг, — пишите. Никто не листает таймлайн ради номера порта.
3. Как часто это меняется? Если экран меняется каждый месяц, текст дешевле поддерживать. Если он стабилен год — видео окупится.

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

Когда побеждает видео

Показать рабочий процесс между несколькими инструментами. Сложность большинства процессов не в отдельном клике, а в том, что происходит между приложениями. Запись фиксирует весь путь, и вам не нужно описывать шесть переключений контекста.

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

Баг-репорты и воспроизведение. Запись показывает точную последовательность, точный тайминг и точное состояние. Она полностью снимает переписку в духе «у меня не воспроизводится».

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

Всё, что иначе пришлось бы объяснять вживую трижды. Если вы сказали одно и то же на трёх встречах, нужна запись, а не четвёртая встреча.

Передать интонацию. Обратная связь, решения с нюансами и всё, что можно прочитать как резкость, воспринимаются гораздо лучше, когда есть голос и лицо.

Когда побеждает текст

Справочные материалы. Значения конфигурации, параметры API, горячие клавиши, коды ошибок. Всё, что ищут, а не изучают.

Всё, что должно находиться поиском. Текст индексируется вашей вики, центром поддержки и поисковыми системами. Видео остаётся чёрным ящиком, пока к нему нет расшифровки.

Шаги, которые часто меняются. Отредактировать строку в документе — секунды. Перезаписать фрагмент, свести звук и заново экспортировать — час. И каждый устаревший кадр подрывает доверие ко всей библиотеке.

Материалы, нужные прямо во время работы. Никто не хочет одной рукой запускать миграцию, а другой ставить видео на паузу и отматывать назад. Чек-листы созданы для чтения.

Юридические, комплаенс- и любые тексты с точными формулировками. Если точность важнее наглядности — пишите, согласуйте и версионируйте.

Контент с большим объёмом перевода. Текст дёшево переводится на четырнадцать языков. Перезапись озвучки — нет.

Формат, который на самом деле нужен большинству команд

Лучшая документация редко бывает чем-то одним. Это короткая запись с текстовым каркасом.

Надёжная схема:

• Текстовая страница как единый источник правды. Заголовок, цель, предварительные условия, пронумерованные шаги и все точные значения копируемым текстом.
• Запись на две-четыре минуты, встроенная ближе к началу. Она показывает форму задачи, чтобы читатель понимал, что ему предстоит.
• Метки глав и таймкоды, чтобы видео стало навигируемым, а не линейным.
• Расшифровка или субтитры, чтобы содержимое видео стало доступным и находилось поиском.

Кому нужна общая картина — смотрит. Кому нужно значение — просматривает текст. Ни одна группа не страдает от выбора другой.

Держите записи достаточно короткими, чтобы они не устаревали

Главная причина, по которой видеодокументация протухает, — длительность. Двадцатиминутную запись с восемью темами приходится переделывать целиком, когда меняется одна тема. Восемь трёхминутных записей заменяются по одной.

Практические правила, которые сохраняют библиотеку видео поддерживаемой:

• Одно видео — один результат. Если в заголовке нужно «и», разделите.
• Цельтесь в пять минут максимум. Большинство объяснений процесса укладывается в три.
• Не записывайте то, что меняется быстрее всего. Цены, даты, названия команд и тексты интерфейса — в текст рядом с видео.
• Произнесите версию вслух или покажите её на экране. «Запись сделана на версии 4.2» превращает устаревшее видео в датированное, а это куда менее вредно.
• Записывайте чисто. Режим «Не беспокоить», демоданные вместо реальных клиентских записей, единая тема. Один ролик, который можно переиспользовать в трёх местах, ценнее трёх, которые нельзя.

Снижайте стоимость записи

Большинство решений «давайте лучше напишем» на самом деле означают «запись ощущается как целое производство». Снизьте эту цену — и расчёт изменится для всей команды.

• Пропустите вступление. Начинайте с экрана, который важен. Внутренней документации не нужны пятнадцать секунд предисловия.
• Не пишите дословный сценарий. Набросайте пять тезисов и говорите по ним. Сценарии заставляют звучать как чтение вслух и утраивают время подготовки.
• Чините монтажом, а не перезаписью. Вырежьте паузы, сбившуюся фразу и долгую загрузку. Почти любой дубль можно спасти.
• Используйте зум вместо пояснений. Приближение к кнопке, на которую вы нажали, заменяет фразу о том, где она находилась.
• Хватит одного хорошего дубля. Внутренней документации не нужна четвёртая попытка. Публикуйте.

Простая командная политика

Если хотите закрыть этот спор, запишите четыре строки:

1. Справочники и конфигурация → текст. Всегда.
2. Процессы, демо и обратная связь → видео. Меньше пяти минут.
3. Всё, чем пользуются во время работы → текстовый чек-лист, с необязательным видеообзором.
4. Всё, что меняется чаще раза в квартал → текст, если только визуал не является сутью.

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

В заключение

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