在 GitHub 文档中使用视频

关于 GitHub Docs 中的视频

在 GitHub Docs 中很少使用视频。当视频对于为文章提供最佳用户体验是必需的时，它们会与书面文本一起使用。视频不能替代书面内容。视频绝不应该是传达信息的唯一方式，因为它们更难保持最新状态，并且并非所有人都能访问。

使用这些指南来确定是否适合在文章或文档中的登陆页面中包含视频。

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

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

视频检查清单

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

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

如果您对其中任何一项回答“否”，则该视频不适合添加到 GitHub 文档中。

维护视频

如果视频有维护计划或有专门负责审核和更新内容的团队（如果内容过时），则可以无需任何其他步骤即可包含该视频。

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

最佳实践

使用这些最佳实践来帮助确定视频是否制作精良，并且质量足够高，可以包含在 GitHub 文档中。

优秀的视频会介绍一个教学议程，其中包括步骤和目标，以便观看者可以快速了解他们将学到什么。视频具有演示性，既展示又解释了执行的相关步骤。视频应该引人入胜且鼓舞人心。视频必须制作精良才能包含在 GitHub 文档中。制作精良的视频几乎不会对残疾人造成障碍，具有专业的旁白（如果是旁白视频），具有清晰的视觉效果，并且来自 GitHub 或 Microsoft 等可信来源。

视频大致分为三类：产品概述、功能视频和教程。这些描述是对每种视频类型的概括。有些视频可能无法完全归入一类，但即使不完全符合确切的指南，它们仍然有用。

产品概述

目的：简要解释产品是什么，展示主要功能，并激发人们的兴趣
长度：不到一分钟
可能的受众：想要了解某个功能是否对自己的目标有用的用户、不了解 GitHub 且试图了解产品功能的新用户
文档中可能的位置：着陆页和指南

功能视频

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

教程

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

何时使用视频

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

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

使用视频来解释它们展示的过程或概念的价值。

何时不使用视频

不要对快速变化且可能使视频过时的功能使用视频。不要使用与书面内容相矛盾或违反“风格指南”任何部分的视频。不要使用仅显示任务而不解释或详细说明过程的视频。视频必须有用且相关，包括随着时间的推移保持准确性。

辅助功能要求

以下是对视频纳入 GitHub 文档的最低要求。如果视频违反了其中任何一项要求，则不能将其添加到文档中。

无闪烁或频闪效果
必须有隐藏式字幕。有关详细信息，请参见下文的“创建视频字幕”
无图形与字幕出现位置重叠
字体必须清晰可读
任何叠加层都必须具有足够的对比度
任何文本都必须在屏幕上显示足够长的时间以供阅读（文本应在屏幕上显示的时间应长于大声朗读两次所需的时间）
必须对逐个场景发生的情况进行校对描述性转录。有关详细信息，请参见下文的“创建视频转录”
视频不会自动播放

创建视频字幕

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

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

字幕指南

如果可能，字幕应与视频中说出的单词完全匹配。不要对字幕进行改写或截断，除非时间限制严重，以至于难以在给定时间内阅读字幕。

字幕必须同步，以便与音频大致同时出现。字幕应始终定时在说话者开始说话时出现在屏幕上。对于快速语音，如果难以阅读与音频精确同步的字幕，您可以在语音结束后将字幕延长显示在屏幕上。

如果视频有多个说话者，请在字幕中识别说话者。在句子的开头添加说话者的姓名或描述性名称，例如 Developer。例如：Jimmy：你好。。您只需要在说话者发生变化时执行此操作，而不是针对每行对话。如果从视觉效果中可以明显看出谁在说话，则无需识别说话者。

字幕必须是一行或两行，每行不超过 32 个字符。将每个新句子放在新行上。如果您需要在句子中间断行，请在逻辑点断行，例如在逗号之后或在 and 或 but 等连词之前。

在 YouTube 上添加和编辑字幕

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

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

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

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

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

如果视频有多个说话人，请在转录中识别说话人。
如果知道说话人的性别，则可以在描述其动作时使用其首选代词。例如，她指向计算机屏幕。如果说话人的性别未知或与所描述的视觉无关，则可以使用单数代词“他们”。
以合乎逻辑的段落、列表和章节格式化转录。如果有助于人们理解内容，则可以为章节添加标题。考虑一下如果不观看视频，人们如何从转录中获取信息。
添加视频中字幕中未包含的任何屏幕文本、相关视觉元素或非言语声音。将这些描述放在视频中伴随它们的语音文本之后。以方括号格式化视觉信息。例如，[播放背景音乐。旁白点击“代码”按钮，然后点击“+ 新代码空间”按钮。]。
将 product_video 属性添加到转录文章的 YAML 前端。product_video 属性的值是视频的 YouTube URL。视频的 YouTube URL 将在转录文章中显示为外部链接。
在转录的末尾，写下 转录结束。并链接到视频中涉及的产品的着陆页，使用模式 有关 PRODUCT 的更多信息，请参阅 [“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

在 GitHub Docs 中使用视频

在本文中