Skip to main content

GitHub Docs 的最佳做法

按照这些最佳做法即可创建用户友好且易于理解的文档。

关于 GitHub 文档

在 GitHub 上,我们努力打造准确、有价值、包容、支持辅助功能,并且易于使用的文档。

在对 GitHub Docs 贡献一份力量之前,请先花点时间让自己熟悉 GitHub 的文档理念和内容设计原则:

编写 GitHub 文档的最佳做法

无论是创建新的文章还是更新现有文章,在编写 GitHub Docs 时都应遵循以下指导准则:

内容要服务于用户需求

开始动笔之前,一定要先了解文章受众是谁、他们的目标是什么、文章将要传达的核心任务或中心思想是什么,以及要写哪种类型的内容。

确定受众

  • 哪些人会阅读这篇内容?
  • 他们正在尝试执行哪种操作?

确定核心用途

  • 阅读本文后,受众应该能够执行什么操作或了解哪些知识? 选择内容将会讨论到的一个或两个任务或概念。
  • 如果其他任务、概念或信息并不必要,则思考如何降低其在文章中的篇幅、移至另一篇文章中,或索性全部删除。

确定内容类型

根据意图受众和内容的核心用途,确定你要编写的内容类型。 GitHub Docs 使用以下内容类型:

例如,使用概念内容类型来帮助读者了解某一个功能或主题的基本信息,以及如何帮助他们实现其目标。 使用过程内容类型来帮助人们从头至尾完成一项具体任务。

结构内容要清晰易读

使用以下最佳做法来构建内容。 将内容添加到现有文章时,请尽可能遵循现有结构。

  • 提供初始上下文。 确定主题并说明其与读者的相关性。
  • 按重要性和相关性,按逻辑顺序构建内容。 按照优先级顺序,以及用户将会需要的顺序放置信息。
  • 句子和段落要避免过于冗长
    • 一个一个介绍概念。
    • 每段使用一个想法。
    • 每个句子使用一个想法。
  • 强调最重要的信息
    • 以最重要的词语和要点为每句话或每个段落开篇。
    • 解释概念时,先从结论开始,然后再更加详细地进行解释。 (有时,这种文章结构称为“总-分结构”。)
    • 解释复杂主题的,先为读者呈现基本信息,然后在文章后面披露详细信息。
  • 使用有意义的子标题。 将相关段落整理到各部分中。 为每个部分提供唯一且准确描述内容的子标题。
  • 请考虑使用页面内链接来获取较长的内容。 这样,读者就可以跳转到感兴趣的区域,并跳过与其无关的内容。

编写时要考虑到可读性

让忙碌的用户能够轻松阅读和理解文本内容。

  • 使用简洁朴素的语言。 尽可能使用常见、日常字词,避免行话。 开发人员熟知的术语固然有其优点,但不要认为读者知道 GitHub 的工作原理的详细信息。
  • 使用主动语态。
  • 简洁。
    • 写简单、简洁的句子。
    • 避免包含多个概念的复杂句子。
    • 逐渐减少不必要的详细信息。

有关相关信息,请参阅 风格指南编写要翻译的内容 中的“语气”。

格式要便于扫描

大多数读者并不会使用文章全文。 而是会_扫描_页面定位到具体信息,或_跳过_页面获取概念的主旨。

扫描或浏览内容时,读者会跳过大量文本。 他们查找与其任务相关的或是页面中显眼的元素,例如,标题、警报、列表、表格、代码块、视觉对象,以及每个部分的头几个字等。

文章明确用途和结构后,就可以运用以下格式设置技巧来优化用于扫描和一眼略过的内容。 这些技巧也有助于让内容更容易被所有读者理解。

  • 使用文本突出显示(粗体和超链接等)吸引读者注意最重要的点。 请谨慎使用文本突出显示。 不要突出显示文章中总文本的 10% 以上。
  • 使用格式设置元素分隔内容并在页面上留白。 例如:
    • 项目符号列表(具有可选的运行子标题)
    • 编号列表
    • 警报
    • 视觉对象
    • 代码块和代码注释

延伸阅读