为 GitHub 文档创建图表

关于 GitHub 文档中的图表

图表使用形状、线条和标签以直观的方式解释概念。我们在 GitHub 文档中使用图表来支持文本信息。

图表并不会降低信息的复杂性，但它们提供了一种不同的方式来接收和处理信息。有些人希望以展示的方式获取信息，而不是阅读。有些人无法理解可视化图表，需要以文本形式呈现信息。

图表有许多用途。图表可以提供概念的高级概述，这些概念需要用段落或整篇文章来撰写。某人可以查看图表，然后决定是否要阅读更多内容以获取其他信息。图表还可以用于系统级决策制定，通过一次查看整个流程或微观级理解工作流中的特定步骤。图表是内容，与所有内容一样，需要仔细考虑用户的需求，以确定如何最好地使用它们。

图表具有创造性。如果你有一个图表创意可以帮助人们，无论它使用什么形状，它都可能非常适合 GitHub 文档。以下要求和建议将帮助你创建可以包含在 GitHub 文档中的图表。

图表清单

要包含在 GitHub 文档中，图表必须满足以下条件。

尽可能多的用户都可以访问图表。
- 图表有清晰的起点且易于理解。
- 图表在出现的文章中之前或之后有完整的文本描述，没有完全以可视化形式传达的信息。
- 图表具有适当的对比度。
- 图表具有适当的备用文本。
- 图表清晰明了，元素尽可能清晰易读。
图表有验收标准并符合这些标准。
- 图表有受众。
- 图表的信息量和密度适中。
图表在视觉上是合理的。
- 图表遵循此内容模型中规定的样式。
- 图表有足够的信息，易于理解和浏览，但不会过度装饰或不必要地复杂。

维护图表

图表创建者负责维护图表。如果图表已过时，GitHub 文档团队有权删除、更新或替换图表。

不使用图表的情况

图表不能替代文本。它们是对文章中书面信息的补充。不要添加图表来尝试简化或修复令人困惑的文章。考虑重写文章文本，如果它支持重写的文本，则可能添加图表。

使用图表的情况

图表可以在 GitHub 文档中使用，当它们对人们有帮助，而不仅仅是视觉装饰时。要确定图表是否有用，它需要包含以下内容的验收标准

图表的目标受众是谁？
图表的作用域是什么？
图表如何补充随附的文本？
你将如何评估图表的效果？

图表必须始终附带完全传达相同信息的文本。

图表验收标准

要为图表创建验收标准，请回答以下问题。

图表的目标受众是谁？

图表与文章一样，可以有广泛或特定的受众。例如，图表受众可能是考虑为其组织购买 GitHub 高级安全性的用户，或者正在学习 GitHub 教育申请流程的学生。

图表中的信息越多，创建和理解起来就越困难。所有图表都需要一个既定的范围来指导其创建和评估其有效性。例如，解释 GitHub 是什么的图表具有非常大的范围。如果它详细介绍每个 GitHub 产品和功能，可能会令人困惑，因此我们希望此范围的图表提供广泛的概述。相比之下，帮助某人评估 GitHub 托管的 runner 还是自托管的 runner 更适合其用途的图表可能会包含更具体和细微的信息，因为它具有更窄的范围。

图表如何补充随附的文本？

图表可以根据其附近的文本提供不同的目的。在系统文本描述之后描绘复杂系统的图表可以提供系统的可视化解释，这将帮助一些人理解整个概念。在说明某人即将执行的任务的程序步骤之前的图表可以帮助一些人做好成功完成任务的准备。图表需要一个它与文本一起完成的目的，并且图表永远不能成为文章中传达信息的唯一方式。

你将如何评估图表的效果？

考虑到受众和范围，你应该能够确定图表需要解释什么才能有效。在将图表包含在 GitHub 文档中之前，请让其他人查看并确定它是否向指定受众解释了预期信息，并具有与范围相适应的详细信息。

选择使用何种类型的图表

不同的人会发现不同的图表有价值，并且创建好的图表既有科学性，也有艺术性。以下一般准则可以帮助你选择使用何种类型的图表，但你也可以拥有一个独特的图表，它更适合你的具体验收标准。

解释时间的图表

如果你要创建一个图表来解释某事何时或如何发生，请考虑以下这些图表类型。

流程图：流程图对于显示流程中的步骤很有用。在此示例中，矩形表示流程中的步骤，菱形表示图表分叉成两个可能端点的决策点。
甘特图：甘特图对于显示任务需要多长时间以及它们何时重叠很有用。在此示例中，水平轴标记为“时间”，蓝色矩形表示三个离散任务。任务 1 和任务 2 重叠，这意味着至少部分任务同时发生。任务 3 与其他任务不重叠，这意味着它在前两个任务完成后发生。
旅程图：旅程图对于显示某事随时间变化的状态很有用。在此示例中，水平轴标记为“时间”，垂直轴标记为“观察或测量到的某事”。蓝色圆点标记特定时间点的测量值，并用线连接起来以说明随时间的趋势。

解释排列的图表

如果你要创建一个图表来解释事物是什么或在哪里，请考虑以下这些图表类型。

框图：框图对于通过将项目放在其他项目中来显示事物的组织方式很有用。此示例显示了内容如何在 GitHub 文档中组织，其中最大的矩形标记为“类别”，该矩形内的一个矩形标记为“映射主题”，该矩形内的一个矩形标记为“文章”。
概念图：概念图对于显示事物之间的关系很有用。带有或不带有标签的不同线条显示事物如何连接或相互影响。在此示例中，四个蓝色矩形表示概念，它们之间的线条显示它们之间的不同关系。
层次结构：层次结构对于显示类别和子类别之间的关系很有用。在此示例中，三个级别的层次结构垂直组织。

解释上下文的图表

如果你要创建一个图表来解释某事为何如此，请考虑以下这些图表类型。

连续统一体图表：连续统一体图表对于显示事物在线性频谱上的位置很有用。在此示例中，蓝色矩形显示感兴趣的项目在连续统一体上更接近选项 2 而不是选项 1。
象限图：象限图可用于解释两个轴之间的关系以及事物在两个轴上的位置。在此示例中，水平轴左侧标记为“纯粹装饰性”，右侧标记为“满足特定验收标准”。垂直轴顶部标记为“补充书面文本”，底部标记为“信息呈现的唯一方式”。标记为“GitHub 文档中的图表”的蓝色正方形位于“补充书面文本”和“满足特定验收标准”重叠形成的右上角象限中，这意味着它具有这两个属性。
韦恩图：韦恩图可用于显示共享特征或思想重叠。圆圈表示概念或事物，圆圈重叠的区域表示事物之间的共享特征。在此示例中，标记为“章鱼”的圆圈和标记为“猫”的圆圈之间的重叠部分标记为“Octocat”，它是章鱼和猫的组合。