在 GitHub Docs 中使用视频

关于 GitHub Docs 中的视频

GitHub Docs 中很少使用视频。当视频对于提供文章的最佳用户体验至关重要时，会将其与书面文本一起使用。视频不能替代书面内容。视频永远不应该成为传递信息的唯一方式，因为它们更难以保持最新，并且并非所有人都可以访问。

使用以下指南确定是否适合在文章或文档中的登录页面中包含视频。

如果您在 GitHub Docs 中添加了指向视频的链接或嵌入视频，请将视频的元数据添加到 github/docs 存储库中的“GitHub Docs 中的视频”文件中。

Docs 团队不创建或维护视频内容。视频纯粹是辅助性的，旨在帮助传达重要或复杂主题，并且应谨慎使用，因为它们不是 Docs 团队拥有的内容类型。

视频清单

使用此清单快速确定是否适合将视频添加到文章或登录页面。

视频是传达信息唯一的方式吗？
GitHub 是否拥有该视频？
视频制作精良吗？（有关更多信息，请参阅“最佳实践”部分。）
视频是否尽可能多地面向最广泛的用户群体？（有关更多信息，请参阅“可访问性要求”部分。）
视频长度是否少于五分钟？
视频在文档中是否有特定的受众和用途？如果它仅与特定产品或功能相关，则必须对其进行版本控制。有关更多信息，请参阅“版本控制”部分。

如果您对任何这些项目的回答为“否”，则该视频不适合添加到 GitHub Docs 中。

维护视频

如果视频具有维护计划或团队直接负责在内容过时时对其进行审核和更新，则您可以包含该视频，无需执行任何其他步骤。

如果视频没有维护计划，请创建一个问题，并指定一个合适的目标日期来审查或删除该视频。

最佳实践

使用以下最佳实践来帮助确定视频的制作是否精良，以及其质量是否足够高，可以包含在 GitHub Docs 中。

好的视频会介绍一个包含步骤和目标的教学议程，以便观看者快速了解他们将学到什么。视频具有演示性，既展示又解释执行的相关步骤。视频应具有吸引力和鼓励性。要包含在 GitHub Docs 中，视频必须制作精良。制作精良的视频对残疾人士的障碍较少，具有专业的旁白（如果是旁白视频），视觉效果清晰，并且来自可信来源，例如 GitHub 或 Microsoft。

视频大致分为三类：产品概述、功能视频和教程。这些描述是对每种视频类型的概括。某些视频可能并不完全适合于某一类，但即使不完全符合指南，仍然可能有用。

产品概述

目的：简要说明产品是什么，展示主要功能，并激发人们的兴趣
长度：少于一分钟
可能的受众：希望了解某个功能是否对他们的目标有帮助的人，以及刚接触 GitHub 并试图了解产品功能的人
文档中的可能位置：登录页面和指南

功能视频

目的：补充概念性或程序性内容
长度：尽可能短，不超过五分钟。将较长的内容分解成多个较短、重点突出的视频
可能的受众：正在了解或学习如何使用某个功能的人
文档中的可能位置：指南、概念性文章、程序性文章

教程

目的：帮助新手用户开始使用产品，推动采用，或解释复杂的功能
长度：单个视频应为五分钟或更短。复杂主题可以在一篇文章中包含一系列较短的视频。总长度应最多为 15 分钟
可能的受众：功能或产品的新用户
可能的位置：指南

何时使用视频

当需要显示移动或状态变化时，我们可能会使用视频而不是其他视觉效果（例如屏幕截图或图表），例如当某人从一个屏幕导航到另一个屏幕或演示涉及浏览多个菜单的功能时。但是，屏幕截图或文本可能足以解释这些过程。

视频还可以帮助介绍功能或产品，其中 30 秒的视频可以补充需要多段文字才能写出的信息。

使用解释其所展示的过程或概念价值的视频。

何时不使用视频

不要将视频用于快速更改的功能，因为这可能会导致视频过时。不要使用与书面内容相矛盾或违反“样式指南”任何部分的视频。不要使用仅显示任务而不解释或详细说明过程的视频。视频必须有用且相关，包括随着时间的推移保持准确性。

可访问性要求

这些是将视频包含在 GitHub Docs 中的最低要求。如果视频违反了任何这些要求，则无法将其添加到文档中。

没有闪烁或频闪效果
必须具有隐藏式字幕。有关更多信息，请参阅下面的“创建视频字幕”。
图形不得与字幕出现的位置重叠
排版必须清晰易读
任何叠加层必须具有足够的对比度比率
任何文本必须在屏幕上显示足够长的时间以供阅读（文本应在屏幕上显示的时间应长于将其大声朗读两次所需的时间）
必须具有校对过的描述性逐场景转录文本。有关更多信息，请参阅下面的“创建视频转录文本”。
视频不会自动播放

创建视频字幕

视频必须在添加到 Docs 网站之前具有人工生成的字幕。您可以使用自动字幕技术来帮助创建字幕，但必须由人工校对和编辑以确保准确性。如果视频托管服务（如 YouTube）具有本机字幕工具，则可以使用该工具准备字幕或创建格式正确的SRT或VTT字幕文件以与视频一起上传。

创建字幕是制作更多人可以访问的视频的一部分，因此添加到 GitHub Docs 的视频所有者应提供字幕。

字幕指南

在可能的情况下，字幕应与视频中所说的内容完全匹配。除非时间限制严重，导致人们难以在给定的时间内阅读字幕，否则不要对字幕进行释义或截断。

字幕必须与音频同步，大致出现在相同的时间点。字幕应始终在说话者开始说话的那一刻显示在屏幕上。对于语速较快的部分，如果难以将字幕精确地与音频同步，可以延长字幕显示时间，使其在语音结束后继续显示在屏幕上。

如果视频有多个说话者，请在字幕中识别说话者。通过在句子开头添加说话者的姓名或描述性名称（例如开发者）来实现这一点。例如：Jimmy：你好。。仅当说话者发生变化时才需要这样做，无需针对每一行对话都进行识别。如果从视觉效果上可以明显看出是谁在说话，则无需识别说话者。

字幕必须为一两行，每行不超过 32 个字符。每个新句子另起一行。如果需要在句子中间换行，请在逻辑点换行，例如在逗号之后或在和或但是等连词之前。

在 YouTube 上添加和编辑字幕

对于托管在 YouTube 上的视频，请参阅 YouTube 文档中的“添加字幕和隐藏式字幕”和“编辑或删除字幕”。

对于文档中链接或嵌入的每个视频，我们都必须有一个描述性的视频文字记录。文字记录文章的格式与其他文章相同，包含 YAML 前置内容和 Markdown 内容。要将文字记录添加到 Docs 网站，请在content/video-transcripts中创建一篇文章，并将文字记录作为文章的正文。为文章指定类似transcript-VIDEO-NAME.md的文件名，并为title前置内容属性指定Transcript - VIDEO NAME的值。将文章添加到video-transcripts目录中的index.md文件中。

不要使用 Liquid 变量或可重用组件来替换文字记录中的产品名称等内容。文字记录应忠实于视频中的音频，并且在视频制作完成后，我们不应因更新变量或可重用组件而更改文字记录中的任何文本。

创建文字记录是制作更多人可以访问的视频的一部分，因此添加到 Docs 网站的视频所有者应提供文字记录的内容。

您可以使用字幕作为文字记录的基础。编辑字幕以删除所有时间戳，并包含下面详细说明的相关信息。描述性文字记录包含理解视频内容所需的音频和视觉信息的文本版本。

如果视频有多个说话者，请在文字记录中识别说话者。
如果已知说话者的性别，则可以在描述其行为时使用其偏好的代词。例如，她指着电脑屏幕。如果说话者的性别未知或与所描述的视觉内容无关，则可以使用单数 they 代词。
以逻辑段落、列表和章节的形式格式化文字记录。如果这对人们理解内容有所帮助，您可以为章节添加标题。考虑一下，如果某人没有观看视频，他们将如何从文字记录中获取信息。
添加字幕中未包含的任何屏幕文本、相关视觉元素或非语音声音。将这些描述放在视频中与其对应的语音文本之后。以括号格式化视觉信息。例如，[背景音乐响起。叙述者单击“代码”按钮，然后单击“+ 新代码空间”按钮。]。
将product_video属性添加到文字记录文章的 YAML 前置内容中。product_video属性的值是视频的 YouTube URL。视频的 YouTube URL 将作为文字记录文章中的外部链接显示。
在文字记录的末尾，写入文字记录结束。，并使用模式有关 PRODUCT 的更多信息，请参阅 [“产品”文档](link/to/landing-page)。链接到视频所述产品的目标网页。

请参阅 W3C 文档中的“包含视觉内容描述的文本文字记录”，以了解音频和视觉转录的更多示例。

从外部托管的视频链接到文字记录

在视频托管平台上的视频描述中添加指向视频文字记录文章的链接。有关更多信息，请参阅 YouTube 文档中的“编辑视频设置”。

链接到嵌入视频的文字记录

在包含嵌入视频的任何内容中，在 YAML 前置内容中product_video属性下方添加product_video_transcript属性。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

本文内容