关于图表 GitHub Docs
关系图使用形状、线条和标签直观地对概念进行解释。 我们使用图表来辅助GitHub Docs中的文字信息。
关系图不会降低信息的复杂程度，但却提供了不同的信息接收和处理方法。 有些人希望显示信息而非读取信息。 有些人无法使用可视化关系图，需要以文本形式显示信息。
关系图的用途有许多。 图表可以为那些需要用段落或整篇文章来描述的概念提供高层次的概览。 有些人可以查看关系图，然后决定是否要了解详细信息。 此外，还可一次性查看整个流程，或对工作流中特定步骤进行微观层面的了解，以便使用关系图进行系统级决策。 图表是内容，与所有内容一样，需要仔细考虑用户需求，以确定如何最好地利用它们。
图表富有创造性。 如果你有一个能帮助人们的图表构想，不管它具体使用什么形状，它都可能很适合 GitHub Docs。 以下要求和建议将帮助你创建可纳入 GitHub Docs 的图表。
关系图清单
若要包含在内 GitHub Docs，关系图必须满足以下条件。
- 用户可以尽可能多地访问关系图。
- 关系图具有明确的起点，易于遵循。
- 图表在文章中出现时，其前后会附有完整的文本说明，信息并非仅通过视觉形式传达。
- 图表具有适当的对比度。
- 图表具有适当的替代文本。
- 图示清晰锐利，所有元素尽可能易读。
- 图表有验收标准并符合这些标准。
- 关系图拥有受众。
- 图表的信息量和密度适当。
- 关系图视觉效果良好。
- 关系图遵循此内容模型规定的样式。
- 关系图提供充足的信息，因此易于理解和导航，但却并不过多修饰或过于复杂。
维护图表
关系图的创建者负责对关系图进行维护。 如果图表已过期，团队 GitHub Docs 可自行删除、更新或替换图表。
何时不使用图表
关系图不能替代文本。 他们对文章中的书面信息进行补充和美化。 请勿通过添加关系图尝试简化或修复令人困惑的文章。 请考虑重写文章内容，并根据需要添加图表以支持重写后的内容。
何时使用图表
图表可以在 GitHub Docs 中使用，前提是它们有助于人们理解内容，而不只是视觉上的点缀。 要确定关系图是否有用，关系图需要满足以下条件：
- 图表的目标受众是谁？
- 关系图的范围是什么？
- 关系图如何补充随附的文本？
- 如何评估关系图的有效性？
关系图必须始终附带充分传达相同信息的文本。
图表的验收标准
要为关系图创建验收条件，请回答这些问题。
图表的目标受众是谁？
图表（如文章）可以面向广泛或特定的受众。 例如，图表的受众可能是正在考虑为其组织购买 GitHub Advanced Security、GitHub Code Security 或 GitHub Secret Protection 的人员，或者是正在了解 GitHub Education 的申请流程如何运作的学生。
关系图的范围是什么？
关系图中的信息越多，创建和理解的难度越高。 所有图表都需要明确的范围来指导它们的创建并评估其有效性。 例如，解释 GitHub 是什么的图示涵盖范围非常广。 如果图中展开介绍每个 GitHub 产品和功能的细节信息，可能会让人感到困惑，因此我们希望这一范围的图示提供一个总体概览。 相比之下，一个帮助用户评估对于其用途而言，GitHub 托管的运行器还是自托管运行器更合适的图表，由于讨论范围更窄，往往会包含更具体、更细致的信息。
关系图如何对随附的文本进行补充？
根据关系图上下文的文本，关系图可以有不同的用途。 一幅在系统文本说明之后的复杂系统示意图可以为系统提供可视化说明，帮助某些人从整体上理解这一概念。 在过程步骤前展示即将要完成任务的图示，能够帮助一些人做好成功完成任务的准备。 图表需要与文本共同实现特定的目的，但绝不能成为文章中传递信息的唯一方式。
如何评估关系图的有效性？
考虑到受众和范围，应该能够确定关系图需要解释哪些内容才能有效。 在GitHub Docs中加入图表之前，请让其他人进行审查，并确认该图表是否能够向指定受众清楚传达预期信息，且详略程度与范围相匹配。
选择要使用的图表类型
不同人员会发现不同关系图具有价值，与科学相同，创建良好的关系图也是一门艺术。 以下通用准则有助于选择要使用的图表类型，但您可能有一个更适合特定验收标准的独特图表。
解释时间的图示
如果要创建关系图来解释情况发生时间或过程，请考虑其中一种关系图类型。
-
流程图：流程图可用于显示流程步骤。 在此示例中，矩形表示流程步骤，菱形表示决策点，其中图表分为两个潜在终结点。
-
甘特图：甘特图可用于显示任务用时和重叠时间。 在此示例中，水平轴标记为“时间”，蓝色矩形表示三个离散任务。 任务 1 和任务 2 重叠，这意味着至少部分任务同时发生。 任务 3 不与其他任务重叠，这意味着在完成前两个任务后会发生这种情况。
-
旅程图：旅程图可用于显示随时间推移的内容状态。 在此示例中，水平轴标记为“时间”，垂直轴标记为“观察到或测量的内容”。 蓝点标记特定时间的度量值，用一条线连接，用以说明随时间推移的趋势。
说明排列的图解
如果要创建关系图来解释具体内容或地点，请考虑其中一种关系图类型。
-
框图：框图可用于显示如何通过将项放入其他项来组织内容。 此示例说明了内容在 GitHub Docs 中是如何组织的：最大的矩形标记为“Category”，其中有一个矩形标记为“Map topics”，该矩形内还有一个矩形标记为“文章”。
-
概念图：概念图可用于显示内容之间的关系。 带标签或不带标签的不同线条显示内容如何相互关联或影响。 在此示例中，四个蓝色矩形表示概念，矩形之间的线条显示其相互之间的不同关系。
-
层次结构：层次结构可用于显示类别和子类别之间的关系。 在此示例中，层次结构的三个层次以垂直方式进行组织。
用于解释上下文的图表
如果要创建关系图来解释情况缘由，请考虑其中一种关系图类型。
-
Continuum 关系图：Continuum 关系图可用于显示线性光谱上发生的情况。 在此示例中，蓝色矩形显示与 Continuum 上的选项 1 相比感兴趣的项更接近选项 2。
-
象限图：象限图可用于解释两个轴之间的关系以及两个轴上发生的情况。 在此示例中，水平轴左侧标记为“纯装饰”，右侧标记为“满足特定验收条件”。 垂直轴顶部标记为“补充写入文本”，底部标记为“显示信息的唯一方式”。 标有“GitHub Docs中的图表”的蓝色方块位于由“补充书面文本”和“满足特定验收标准”重叠形成的右上象限，这意味着它具有这两个属性。
-
维恩图：维恩图可用于显示共享特征或想法重叠。 圆圈表示概念或内容，圆圈重叠区域表示内容的共同特征。 在此示例中，标记为“Octopus”的圆圈与标记为“Cat”的圆圈之间的重叠部分标记为“Octocat”，即 Octopus 和 Cat 的组合。
样式指南
请遵循以下规则，创建符合 GitHub Docs 样式的图表。
形状
形状表示关系图中的对象或概念。
可以使用 UI 中的元素 GitHub （如 octicons、菜单或按钮）创建关系图（如果它们相关且清晰）。
对于自定义关系图形状，请使用这些形状获取其关联含义。
- 矩形：内容、对象、想法。
- 矩形堆栈：多个类似内容。
- 菱形：某人遵循关系图流做出的决定。
- 圆圈、星形或其他形状：需有别于矩形所表示的任何内容的独特内容。
形状的排列方式可以传达含义。
- 形状位于其他形状中：该形状属于其他形状的一部分。
- 形状有箭头指向其他形状：该形状产生其他形状。
- 形状缩进显示在形状下方：该形状属于其中一种类型。
- 形状通过线条与其他形状相连：该形状与其他形状相关。 线条的粗细可以传达更多含义，粗线表示联系牢固，虚线表示联系脆弱。
- 一种形状覆盖在另一种形状上：它们是相同的。
行
线条表示关系图中各形状的相互关系。
使用不同类型的线条传达关系的其他含义。
- 无方向线条：关联
- 右箭头结尾的单向线条：显示序列或指向对象。
- 两端均有箭头的双向线条：表示互换。
- 括号：建立层次结构。 一般情况下垂直组织括号，以便更轻松地在网页上导航。 缩进层次结构的各个层次。
标签
标签为可视化标记和口头标记。 标签长度应不超过 25 个字符。 要增加标签的对比度，请将文本置于矩形中。 创建图表接近尾声时通常更容易进行标注。
“按键”
通过解释图形的不同元素或明确阐明关系，密钥有助于用户理解。 并非每个关系图都需要密钥。
密钥无法引入关系图中不存在的新信息。 密钥无法修复过于复杂的关系图。 密钥不应定义标记欠佳的对象或关系。
密钥应用于解释形状、颜色或其他视觉元素。 密钥还可以包括缩放和操作的引文或说明。 密钥可以包括部分指令，例如在流程图中的起始位置，但大多数指令应位于引入关系图的文本中。
颜色
如果关系图需要使用颜色，请使用 Primer Design System 中定义的颜色。 要使更多人能够访问关系图，不可将颜色作为传达信息的唯一方法。 例如，如果使用颜色表示关系，还须使用线条或其他视觉元素来传达相同信息。
图表 GitHub Docs 的首选颜色包括：
| 颜色 | 十六进制代码 |
|---|---|
| 黑色 | #24292f |
| 蓝色 | #0969DA |
| 灰色 | #57606a |
| 绿色 | #1a7f37 |
| 紫色 | #8250df |
| 红色 | #cf222e |
技术规范
- PNG 文件格式
- 仅限使用静态图像（不含gif）
- 文件大小不超过 250 KB
- 采用描述性的文件名，例如
merge-conflict-diagram.png，而不是diagram-02.png
如需创建难以在低分辨率查看的关系图，请在相关存储库或其他适当位置纳入指向放大版关系图的链接。 有关示例，请参阅 Actions Runner Controller。
关系图创建工具
建议使用 Figma 工具生成图示，可以访问 Primer 颜色和其他资产。 但也可根据偏好使用其他程序。 遵循上述样式指南中的形状约定，并使用 Primer Design System 中定义的颜色。
辅助功能
图表必须具有正确的对比度和替代文本。
如果使用 Primer Design System 中定义的颜色，则关系图应具有适当的对比度。 若要检查在其他背景色上的对比度，请使用颜色对比度分析器。
为关系图编写替换文字，描述关系图的外观及其包含在文章中的原因。 请勿尝试在替代文本中解释关系图传达的所有内容，因为内容过长会影响实用性。 有关编写替换文字的详细信息，请参阅 风格指南。
关系图中的所有信息还须通过关系图随附文本传达。
版本控制
某些关系图适用于所有GitHub计划（GitHub Free、、GitHub ProGitHub Team和GitHub Enterprise CloudGitHub Enterprise Server）。 在这种情况下，不需要版本控制。
如果关系图仅与某些计划或版本 GitHub Enterprise Server相关，则必须使用 Liquid 条件语句对关系图进行版本控制。 可能需要在最初创建内容时添加此版本信息，也可能需要在因功能更新或 GitHub Enterprise Server 发布而更新内容时添加。
如果关系图仅与某些版本相关并且可能很快过期，请考虑便于维护的选项是否更适合传达必要的信息。
源代码管理
关系图存储在 assets/images/help/ 存储库的 docs 目录下的相关目录中。 如果要创建新关系图，请将其添加到适当文件夹中。 如果要更新现有关系图，请将现有关系图替换为更新版本。
创建新关系图时，将其添加到 Docs Figma 团队中的“关系图”项目中，或向 Docs 团队成员提供 Figma 文件副本。 如果在另一个程序中创建关系图，则如果它满足本指南中的要求和建议，则可以将其包含在 GitHub Docs 其中，但如果它过期，则更有可能将其删除，而不是更新。
示例
有效地使用其他矩形中的矩形，直观地解释云中包含的代码空间部分，并使用箭头显示托管在云中的代码空间和本地编辑器之间的关系。
