为 GitHub 文档创建图表

本指南解释了何时以及如何为 GitHub 文档创建图表。

本文内容

GitHub 文档中的图表概述

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

图表并不会让信息变得不那么复杂，但它们提供了一种不同的接收和处理信息的方式。有些人希望看到信息而不是阅读文字。也有些人无法使用可视化图表，需要以文本形式呈现信息。

图表有多种用途。图表可以提供对需要用段落甚至整篇文章才能阐述的概念的高级概览。读者可以先查看图表，然后决定是否想进一步阅读获取更多信息。图表还可以用于系统层面的决策，通过一次性查看整个过程，或在工作流的特定步骤上进行微观层面的理解。图表是内容的一部分，和所有内容一样，需要仔细考虑用户需求，以确定最佳的使用方式。

图表富有创意。如果你有一个能帮助他人的图表想法，无论使用何种具体形状，都可能适合用于 GitHub 文档。以下要求和建议将帮助你创建可以纳入 GitHub 文档的图表。

图表检查清单

要纳入 GitHub 文档，图表必须满足以下标准。

  • 图表应尽可能被更多用户访问。
    • 图表具有清晰的起点，易于跟随。
    • 图表在出现的文章中应有完整的文字描述在其前后，且不应有信息仅以可视形式传达。
    • 图表具有适当的对比度。
    • 图表具有适当的替代文本。
    • 图表清晰锐利，元素尽可能易读。
  • 图表具有接受标准并满足这些标准。
    • 图表有明确的受众。
    • 图表信息量和密度适中。
  • 图表在视觉上是合理的。
    • 图表遵循本内容模型中规定的风格。
    • 图表信息足够，使其易于理解和浏览，但不过度装饰或不必要地复杂。

维护图表

图表的创建者负责对其进行维护。如果图表过时，由 GitHub 文档团队自行决定删除、更新或替换该图表。

何时不使用图表

图表不能替代文字。它们是对文章中书面信息的补充。不要为了简化或修正一篇令人困惑的文章而添加图表。应考虑先重写文章文本，若图表能支持重写后的文本，再考虑添加图表。

何时使用图表

当图表能够帮助用户且不仅仅是视觉装饰时，可在 GitHub 文档中使用。为了判断图表是否有帮助，需要包含以下内容的接受标准：

  • 图表的受众是谁？
  • 图表的范围是什么？
  • 图表如何补充随附的文本？
  • 你将如何评估图表的有效性？

图表必须始终配有能够完整传达相同信息的文字说明。

图表的接受标准

要为图表制定接受标准，请回答以下问题。

图表的受众是谁？

图表和文章一样，可以面向广泛或特定的受众。例如，图表的受众可能是考虑为其组织购买 GitHub Advanced Security、GitHub Code Security 或 GitHub Secret Protection 的人员，或是学习 GitHub Education 申请流程的学生。

图表的范围是什么？

图表信息越多，创建和理解就越困难。所有图表都需要确定范围，以指导其创建并评估其有效性。例如，解释 GitHub 是什么的图表范围非常大。如果在其中详细说明每个 GitHub 产品和功能，可能会导致混乱，因此此类图表应提供概览。而解释在 GitHub 托管的运行器与自行托管的运行器哪种更适合某些使用场景的图表，则范围更窄，可以深入更具体、细致的信息。

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

图表的作用取决于其所在的文本。位于系统描述文本旁的图表可以提供系统的可视化解释，帮助部分人整体理解概念。位于步骤前的图表可以展示即将执行的任务，帮助人们准备顺利完成任务。图表必须与文本共同实现某一目的，且图表永远不能是文章中唯一的信息传递方式。

你将如何评估图表的有效性？

结合受众和范围，你应该能够明确图表需要解释的内容，以确保其有效。在将图表纳入 GitHub 文档之前，请让其他人审阅并判断它是否以适当的细节向指定受众解释了预期信息。

选择使用哪种类型的图表

不同的人对不同的图表有不同的价值评判，创建优秀图表既是艺术也是科学。以下通用指南可帮助你选择使用哪种图表类型，但你也可能拥有更适合特定接受标准的独特图表。

解释时间的图表

如果你要创建图表来说明某事何时或如何发生，请考虑以下图表类型。

  • 流程图：流程图用于展示过程的各步骤。在此示例中，矩形代表过程步骤，菱形代表决策点，图表在此分支为两个可能的终点。

    An example flowchart that uses rectangles to represent steps in a process and a diamond to represent a decision point where the chart branches.

  • 甘特图：甘特图用于显示任务的持续时间以及它们的重叠情况。在此示例中，水平轴标记为“时间”，蓝色矩形代表三个独立任务。任务 1 和任务 2 重叠，表示它们的部分时间同时进行。任务 3 与其他任务不重叠，表示它在前两个任务完成后才进行。

    An example Gantt chart that has three tasks arranged on a horizontal axis labeled "Time".

  • 旅程图：旅程图用于展示某事随时间的状态变化。在此示例中，水平轴标记为“时间”，垂直轴标记为“观察或测量的事物”。蓝色点标记特定时间的测量值，并通过线条连接以展示随时间的趋势。

    An example journey map that has a line on two axes tracking events over time that we want to observe or measure something about.

解释布局的图表

如果你要创建图表来说明事物是什么或在哪里，请考虑以下图表类型。

  • 块图：块图用于展示事物的组织方式，即将项目嵌套在其他项目中。此示例展示了 GitHub 文档中内容的组织结构：最大的矩形标记为“类别”，其内部的矩形标记为“映射主题”，再内部的矩形标记为“文章”。

    A block diagram of the GitHub Docs content model with overlapping squares showing articles within map topics within categories.

  • 概念图：概念图用于展示事物之间的关系。带或不带标签的不同线条表示事物的连接或相互影响。在此示例中，四个蓝色矩形代表概念，矩形之间的线条展示了它们之间的各种关系。

    An example concept map that shows relationships between four blue rectangles labeled A, B, C, and D.

  • 层级：层级用于展示类别与子类别之间的关系。在此示例中，层级的三级结构垂直排列。

    An example hierarchy that shows two levels of subcategories beneath a main category.

解释上下文的图表

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

  • 连续体图：连续体图用于展示事物在线性光谱上的位置。在此示例中，蓝色矩形显示感兴趣的项目在连续体上更接近选项 2 而非选项 1。

    An example continuum with a horizontal axis representing the continuum between two options and the position of an item on the continuum.

  • 象限图：象限图用于解释两个坐标轴之间的关系以及事物在两轴上的位置。在此示例中，水平轴左侧标记为“纯装饰”，右侧标记为“满足特定接受标准”。垂直轴顶部标记为“补充书面文本”，底部标记为“信息唯一呈现方式”。标记为“GitHub 文档中的图表”的蓝色方块位于右上象限，即同时满足“补充书面文本”和“满足特定接受标准”。

    An example quadrant diagram with four quadrants created by two axes and a blue rectangle in the upper right quadrant.

  • 维恩图：维恩图用于展示共享特征或理念的重叠。圆形代表概念或事物，圆形重叠的区域表示事物之间的共享特征。在此示例中，标记为“章鱼”的圆与标记为“猫”的圆的重叠区域标记为“Octocat”，即章鱼和猫的组合。

    An example Venn diagram with two circles overlapping: one labeled "Octopus" and the other "Cat". The intersection of the circles is labeled "Octocat".

风格指南

遵循以下规则创建符合 GitHub 文档风格的图表。

形状

形状代表图表中的对象或概念。

如果相关且易读，可使用 GitHub UI 中的元素，如 Octicon、菜单或按钮来创建图表。

对于自定义图表形状，请使用以下形状对应其含义。

  • 矩形：事物、对象、想法。
  • 矩形堆叠：多个相同事物。
  • 菱形：在遵循图表流程时作出的决策。
  • 圆形、星形或其他形状：需要区别于矩形表示的独特事物。

形状的排列可传达含义。

  • 形状位于另一个形状内部：这属于该形状的一部分。
  • 形状带有指向另一形状的箭头：这引导至该形状。
  • 形状在另一形状下缩进：这是一种该形状的类型。
  • 形状通过线条连接至另一形状：这与该形状相关。线条粗细可传达进一步含义，粗线表示强连接，虚线表示弱连接。
  • 形状与另一形状重叠：这相当于该形状。

线条

线条表示图表中形状之间的关系。

使用不同类型的线条来传达关系的附加含义。

  • 无方向线：关联Two blue rectangles connected by a non-directional line.
  • 单向线（末端带箭头）：展示顺序或指向对象。Two blue rectangles connected by a line with an arrow on the right end.
  • 双向线（两端都有箭头）：表示相互性。Two blue rectangles connected by a line with an arrow on both ends.
  • 括号：建立层级。通常将括号垂直排列，以便在网页上更易导航。对层级的每一级进行缩进。Two examples demonstrating the difference between vertical (left) and horizontal (right) arrangement of three rectangles connected by brackets.

标签

标签是视觉和文字标记。标签应控制在 25 个字符以内。为提高标签对比度，可将文字放入矩形中。通常在创建图表后期添加标签更为容易。

键

键通过解释图形的不同元素或明确阐明关系来帮助理解。并非所有图表都需要键。

键不得引入图表中不存在的新信息。键不能修复过于复杂的图表。键不应为标记不清的对象或关系定义说明。

键用于解释形状、颜色或其他视觉元素。键还可包含引用或对比例和操作的说明。键可以包括一些指示，如流程图的起始位置，但大部分指示应在介绍图表的正文中提供。

颜色

如果图表需要颜色，请使用 Primer 设计系统 中定义的颜色。为使图表对更多人可访问，颜色不能是唯一的信息传递方式。例如，若使用颜色表示关系，还必须使用线条或其他视觉元素来传达相同信息。

GitHub 文档中图表的首选颜色如下

颜色十六进制代码
黑色#24292f
蓝色#0969DA
灰色#57606a
绿色#1a7f37
紫色#8250df
红色#cf222e

技术规格

  • PNG 文件格式
  • 仅限静态图像（不支持 GIF）
  • 文件大小不超过 250 KB
  • 使用具描述性的文件名，例如 merge-conflict-diagram.png 而非 diagram-02.png

如果需要创建在低分辨率下难以查看的图表，请在相关仓库或其他适当位置提供指向更大版本图表的链接。示例请参见 Actions Runner Controller。

创建图表的工具

推荐使用的图表工具是 Figma，这样可以使用 Primer 颜色和其他资源。但如果你更喜欢，也可以使用其他程序。遵循上面风格指南中的形状约定，并使用 Primer 设计系统 中定义的颜色。

可访问性

图表必须具备适当的对比度和替代文本。

如果使用 Primer 设计系统中定义的颜色，图表应具备适当的对比度。若需检查其他背景颜色的对比度，请使用 颜色对比度分析工具。

为图表编写替代文本，说明图表的外观以及为何在文章中出现。不要在替代文本中尝试解释图表的全部信息，以免过长失去实用性。有关编写替代文本的更多信息，请参见 风格指南。

图表中的所有信息必须在随附的文字中同样传达。

版本控制

部分图表适用于所有 GitHub 计划（GitHub Free、GitHub Pro、GitHub Team、GitHub Enterprise Cloud 和 GitHub Enterprise Server），此类图表无需进行版本控制。

当图表仅与某些计划或特定版本的 GitHub Enterprise Server 相关时，必须使用 Liquid 条件语句进行版本控制。此版本控制可能在内容首次创建时添加，也可能在内容因功能更新或 GitHub Enterprise Server 发行版更新而修改时添加。

如果图表仅适用于某些版本且容易快速过时，请考虑是否有更易维护的方式来传达必要信息。

源码管理

图表存放在 docs 仓库的 assets/images/help/ 相关目录下。创建新图表时，请将其添加到相应文件夹；更新已有图表时，请使用更新后的版本替换原图表。

创建新图表时，请将其添加至 Docs Figma 团队的 Diagrams 项目，或将 Figma 文件副本提供给 Docs 团队成员。若在其他程序中创建图表，只要满足本指南的要求和建议，即可纳入 GitHub 文档，但若过时，更有可能被删除而非更新。

示例

此图表来源于 GitHub Codespaces 入门指南，巧妙地使用矩形嵌套矩形，直观地说明了代码空间的哪些部分位于云端，并通过箭头展示了托管在云端的代码空间与本地编辑器之间的关系。

Diagram showing the relationship between a code editor and a codespace running on an Azure virtual machine.

© . This site is unofficial and not affiliated with GitHub, Inc.