Использование видео в документациях GitHub

В этом руководстве объясняется, как создавать видео, поддерживающие потребности пользователей в GitHub Docs.

В этой статье

О видео в GitHub Docs

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

Используйте эти рекомендации, чтобы определить, подходит ли видео в статью или на целевой странице в документации.

Если вы добавляете ссылку на видео или внедряете видео в GitHub Docs, добавьте метаданные видео в файл GitHub Docs в репозитории github/docs .

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

Контрольный список видео

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

Если ответить "нет" на любой из этих элементов, видео не подходит для добавления в GitHub Docs.

Обслуживание видео

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

Если видео не имеет расписания обслуживания, создайте проблему с соответствующей целевой датой для просмотра или удаления видео.

Рекомендации

Используйте эти рекомендации, чтобы определить, хорошо ли производится видео и имеет достаточно высокое качество, чтобы быть включены в GitHub Docs.

Хорошие видеоролики представляют обучающую повестку дня, которая включает шаги и цели, чтобы кто-то смотрел быстро знает, что они будут учиться. Видео демонстрируется и показывает, и объясняет соответствующие шаги, выполняемые. Видео должно быть привлекательным и обнадеживающим. Видео должно быть хорошо создано для включения в GitHub Docs. Хорошо созданный видео содержит несколько барьеров для людей с ограниченными возможностями, имеет профессиональное повествование (если это экранное видео), имеет четкие визуальные элементы и поставляется из надежного источника, например GitHub или Майкрософт.

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

Обзоры продуктов

  • Цель: Кратко объяснить, что такое продукт, продемонстрировать основные функциональные возможности и получить заинтересованных людей
  • Длина: менее минуты
  • Возможные аудитории: люди, которые хотят знать, полезна ли функция для своих целей, люди, которые являются новыми для GitHub и пытаются понять, что делают продукты
  • Возможные расположения в документации: целевые страницы и руководства

Видео о функциях

  • Назначение. Дополнение концептуального или процедурного содержимого
  • Длина: как можно короче, без превышения пяти минут. Разорвать более длинное содержимое на несколько коротких, ориентированных видео
  • Возможные аудитории: люди, которые учатся или как использовать функцию
  • Возможные расположения в документации: руководства, концептуальные статьи, процедурные статьи

Учебники

  • Цель: помочь новичкам приступить к работе с продуктом, внедрением диска или объяснить сложные функциональные возможности.
  • Длина: отдельные видео должны быть пять минут или меньше. Сложные темы могут содержать ряд коротких видео, распространяемых по статье. Общая длина должна быть не более 15 минут
  • Возможные аудитории: новые пользователи функций или продуктов
  • Возможные расположения: руководства

Когда следует использовать видео

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

Видео также может быть полезно ввести функции или продукты, где 30 секундное видео может дополнять информацию, требующую записи нескольких абзацев.

Используйте видео, объясняющие значение процедуры или концепции, отображаемой ими.

Когда не использовать видео

Не используйте видео для функций, которые быстро изменяются и могут не обновлять видео. Не используйте видео, которые противоречат написанному содержимому или нарушают любые части Руководство по стилю. Не используйте видео, которые просто показывают задачу, не объясняя или разрабатывая процедуру. Видео должно быть полезным и актуальным, в том числе оставаться точным с течением времени.

требований к специальным возможностям;

Это минимальные требования для включения видео в GitHub Docs. Если видео нарушает какие-либо из этих требований, его нельзя добавить в документы.

  • Нет эффектов мигания или строба
  • Должны иметь закрытые подписи. Дополнительные сведения см. в разделе "Создание заголовков видео" ниже
  • Графики не перекрываются с тем, где отображаются субтитры
  • Типография должна быть удобочитаемой
  • Любые наложения должны иметь достаточное соотношение контрастности
  • Любой текст должен быть на экране достаточно длинным для чтения (текст должен отображаться на экране дольше, чем требуется для чтения его вслух)
  • Должен иметь правописательные расшифровки для того, что происходит сцена по сцене. Дополнительные сведения см. в разделе "Создание расшифровок видео" ниже
  • Видео не выполняет автоматическое воспроизведение

Создание субтитров видео

Перед добавлением на сайт Документации видео должны быть созданные человеком субтитры. Вы можете использовать технологию автозаписи для создания подписей, но они должны быть правописаемыми и изменены для точности человеком. Если в службе размещения видео есть собственный инструмент субтитров, например YouTube, вы можете использовать это средство для подготовки подписей или создания правильно отформатированного SRT или VTT транскрибированного файла для отправки видео.

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

Рекомендации по подписям

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

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

Если видео содержит несколько динамиков, определите динамиков в подписях. Для этого добавьте имя говорящего или описательное имя, например Developerдо начала предложения. Например: Jimmy: Hello.. Это необходимо сделать только при изменении динамиком, а не для каждой линии диалога. Если это очевидно из визуальных элементов, которые говорят, вам не нужно идентифицировать говорящего.

Подписи должны быть одним или двумя строками, и не более 32 символов на строку. Поместите каждое новое предложение в новую строку. Если необходимо разбить строку в середине предложения, сделайте это в логической точке, например после запятых или перед сочетаниями, как and или but.

Добавление и редактирование подписей на YouTube

Видео, размещенные на YouTube, см. в разделе "Добавление субтитров и подписей" и "Изменение" или удаление подписей в документации YouTube.

Создание расшифровок видео

Для каждого видео, связанного или внедренного в документы, необходимо иметь описательную расшифровку видео. Статьи расшифровки форматируются как другие статьи, с содержимым frontmatter и Markdown YAML. Чтобы добавить расшифровку на сайт документов, создайте статью content/video-transcriptsи добавьте расшифровку в качестве текста статьи. Присвойте статье имя файла, например transcript-VIDEO-NAME.md и title свойство Transcript - VIDEO NAMEfrontmatter. Добавьте статью index.md в файл в video-transcripts каталоге.

Не используйте переменные Liquid или повторно используемые для замены таких элементов, как имена продуктов в расшифровке. Транскрибирование должно быть верным звуку в видео, и мы не должны изменять текст в расшифровке в результате обновления переменной или повторного использования после создания видео.

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

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

  • Если видео содержит несколько динамиков, определите динамиков в стенограмме.
  • Если пол говорящего известен, при описании своих действий можно использовать их предпочтительные существительные. Например, She points to the computer screen. если пол говорящего неизвестен или не имеет значения для описанного визуального элемента, можно использовать единственное значение, к котором они имеют место.
  • Форматирование расшифровки в логических абзацах, списках и разделах. Если это поможет людям понять содержимое, вы можете добавить заголовки в разделы. Рассмотрим, как кто-то получит информацию из расшифровки, если они также не просматривают видео.
  • Добавьте любой текст на экране, соответствующие визуальные элементы или звуки, не включенные в субтитры. Поместите эти описания после устного текста, сопровождающего их в видео. Форматирование визуальных сведений в скобках. Например, [Background music plays. The narrator clicks the Code button and then the "+ New codespace" button.].
  • product_video Добавьте свойство в frontmatter YAML статьи о транскрибировании. Значение product_video свойства — URL-адрес видео YouTube. URL-адрес YouTube видео будет отображаться как внешняя ссылка в статье о расшифровке.
  • В конце расшифровки напишите End of transcript. и свяжите ссылку на целевую страницу для продукта, о том, как использовать шаблон For more information about PRODUCT, see the ["Product" documentation](link/to/landing-page)..

Дополнительные примеры транскрибирования аудио и визуальных транскрибирования см. в разделе "Описание визуальных элементов" в документации W3C.

Связывание с транскрибированием из внешних размещенных видео

Добавьте ссылку на статью с расшифровкой видео в описании видео на платформе, где она размещена. Дополнительные сведения см. в разделе "Изменение параметров видео" в документации по YouTube.

Связывание с транскрибированием для внедренных видео

В любом содержимом с внедренным видео добавьте product_video_transcript свойство под product_video свойством в интерфейсном элементе YAML. Значением product_video_transcript является ссылка на статью о расшифровке в каталоге video-transcripts .

title: Example product landing page
product_video: 'https://www.youtube-nocookie.com/embed/URL'
product_video_transcript: /content/video-transcripts/TRANSCRIPT-TITLE

Названия видео

Названия должны быть описательными и следовать рекомендациям по заголовкам в con режим палатки l. Дополнительные сведения см. в разделе Содержимое статьи GitHub Docs.

Управление версиями

Если видео относится только к определенным продуктам GitHub (бесплатно, pro и team; GitHub Enterprise Server; и GitHub Enterprise Cloud), видео должно быть версия для этих продуктов. Используйте условные инструкции Liquid для правильной версии видео. При первоначальном создании содержимого может потребоваться добавить условное управление версиями Liquid или добавить его при обновлении содержимого для обновления компонентов или GitHub Enterprise выпуска. Дополнительные сведения об условных инструкциях и версиях liquid см. в разделе Документация по управление версиями.

Размещение видео

Видео должно размещаться где-то, где принадлежит GitHub и может предоставить команде документации доступ к ним. Видео не должно отслеживать пользователей или использовать файлы cookie. В настоящее время GitHubвидео размещаются на YouTube и добавляются в документы с помощью расширенного режима конфиденциальности, изменив домен для внедренного URL-адреса на https://www.youtube.com/VIDEO https://www.youtube-nocookie.com/VIDEO.