在 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，视频的所有者应该提供字幕。

字幕准则

字幕应尽可能地与视频中讲出的字词完全匹配。不要改写或截断字幕，除非时间存在极高的限制，让人难以在给定时间完成字幕阅读。

字幕必须同步为与音频内容几乎同时出现。应对字幕的出现时间进行控制，使其在说话人开始说话时出现在屏幕上。在说话人讲话较快的情况下，很难准确地阅读与音频同步的字幕，可以延长字幕的存在时间（至说话结束之后）。

如果视频中存在多位说话人，请在字幕中标识不同的说话人。为此，请在句子开头处添加说话人的姓名或描述性名称，例如 Developer。例如：Jimmy: Hello.。只需在说话人更改时执行此操作，而不是在每句话之前都添加该内容。如果从视觉上能轻松识别说话人，则无需标识说话人。

字幕必须是一行或两行，且每行不超过 32 个字符。新说出的每句话都要另起一行。如果需要在句子中分隔行，请在符合逻辑的地方分行，例如在逗号之后或在 and 或 but 等连词之前分行。

在 YouTube 上添加和编辑字幕

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

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

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

创建脚本是制作更多人能观看的视频的过程的一环，所以若要将视频添加到 Docs 站点，视频的所有者应该提供脚本内容。

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

如果视频中存在多位说话人，请在脚本中标识不同的说话人
按照有逻辑的段落、列表和章节来设置脚本格式。在能帮助用户理解内容的情况下，可以添加章节标题。请思考没有观看视频的人如何通过脚本获取信息
添加字幕中不包含的屏幕文本、相关视觉元素或非语音声音。将这些说明放在视频中附带的口述文本后面。用方括号设置视觉对象信息的格式。例如： [Background music plays. The narrator clicks the Code button and then the "+ New codespace" button.]
将 product_video 属性添加到脚本文章的 YAML 前辅文。 product_video 属性的值是视频的 YouTube URL。视频的 YouTube URL 将在脚本文章中显示为外部链接
在脚本末尾，适用 For more information about PRODUCT, see the ["Product" documentation](link/to/landing-page). 模式链接到视频介绍的产品的登陆页面

有关音频和视觉听录的更多示例，请参阅 W3C 文档中的“带有视觉对象说明的文本脚本”。

链接到外部托管视频的脚本

在托管视频的平台上的视频说明中添加文章的链接，其中包含视频的脚本。有关详细信息，请参阅 YouTube 文档中的“编辑视频设置”。

链接到嵌入视频的脚本

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