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

О видео в GitHub Docs

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

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

Если вы добавляете ссылку на видео или внедряете видео в файл GitHub Docs, добавьте метаданные видео в файл {% данных variables.product.prodname_docs %}" в репозитории github/docs .

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

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

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

Является ли видео единственным способом обмена информацией?
Принадлежит ли GitHub видео?
Хорошо ли производится видео? (См. "Дополнительные сведения см. в разделе "Рекомендации".
Доступно ли видео самой широкой группе пользователей? (См. "Дополнительные сведения см. в разделе "Требования к специальным возможностям".
Видео менее чем за пять минут?
Имеет ли видео определенную аудиторию и цель в документации? Если оно относится только к конкретному продукту или компоненту, необходимо его версию. Дополнительные сведения см. в разделе "Управление версиями".

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Добавление и редактирование подписей на 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.