# GitHub Docs 的最佳实践

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

## 关于 GitHub 文档

我们在 GitHub 努力创建准确、有价值、包容、可访问且易于使用的文档。

在参与 GitHub Docs之前，请花点时间熟悉 GitHub文档理念、基础知识和内容设计原则：

* [关于 GitHub 的文档理念](/zh/enterprise-server@3.22/contributing/writing-for-github-docs/about-githubs-documentation-philosophy)
* [关于 GitHub 的文档基础知识](/zh/enterprise-server@3.22/contributing/writing-for-github-docs/about-githubs-documentation-fundamentals)
* [内容设计原则](/zh/enterprise-server@3.22/contributing/writing-for-github-docs/content-design-principles)

## 编写 GitHub 文档的最佳做法

无论是创建新文章还是更新现有文章，在撰写 GitHub Docs以下文章时应遵循以下准则：

* [内容要服务于用户需求](#align-content-to-user-needs)
* [结构内容要清晰易读](#structure-content-for-readability)
* [编写时要考虑到可读性](#write-for-readability)
* [格式要便于扫描](#format-for-scannability)

## 内容要服务于用户需求

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

### 确定受众

* 哪些人会阅读这篇内容？
* 他们试图做什么？

### 确定核心用途

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

### 确定内容类型

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

* [概念内容类型](/zh/enterprise-server@3.22/contributing/style-guide-and-content-model/concepts-content-type)
* [引用内容类型](/zh/enterprise-server@3.22/contributing/style-guide-and-content-model/reference-content-type)
* [操作方法内容类型](/zh/enterprise-server@3.22/contributing/style-guide-and-content-model/how-to-content-type)
* [故障排除内容类型](/zh/enterprise-server@3.22/contributing/style-guide-and-content-model/troubleshooting-content-type)
* [快速入门内容类型](/zh/enterprise-server@3.22/contributing/style-guide-and-content-model/quickstart-content-type)
* [教程内容类型](/zh/enterprise-server@3.22/contributing/style-guide-and-content-model/tutorial-content-type)

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

## 将内容结构化以提高可读性

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

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

## 编写时要考虑到可读性

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

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

有关相关信息，请参阅 [风格指南](/zh/enterprise-server@3.22/contributing/style-guide-and-content-model/style-guide#voice-and-tone) 和 [编写要翻译的内容](/zh/enterprise-server@3.22/contributing/writing-for-github-docs/writing-content-to-be-translated) 中的“语气”。

## 格式要便于扫描

大多数读者并不会使用文章全文。 而是会\_扫描\_页面以定位具体信息，或者\_浏览\_页面以获取概念的大意。

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

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

* **使用文本突出显示**（粗体和超链接等）吸引读者注意最重要的点。 请谨慎使用文本突出显示。 不要突出显示文章中总文本的 10% 以上。
* **使用格式设置元素**分隔内容，并在页面上创建空白。 例如：
  * 项目符号列表（具有可选的运行子标题）
  * 编号列表
  * [警报](/zh/enterprise-server@3.22/contributing/style-guide-and-content-model/style-guide#alerts)
  * 表
  * 视觉效果
  * 代码块和代码注释

## 其他阅读材料

* [风格指南](/zh/enterprise-server@3.22/contributing/style-guide-and-content-model/style-guide)
* [关于内容模型](/zh/enterprise-server@3.22/contributing/style-guide-and-content-model/about-the-content-model)
* [GitHub Docs 文章的内容](/zh/enterprise-server@3.22/contributing/style-guide-and-content-model/contents-of-a-github-docs-article)
* [可读性准则](https://readabilityguidelines.co.uk/)，Content Design London
* [重写数字内容，追求简洁](https://www.nngroup.com/articles/rewriting-content-brevity/)，Nielsen Norman Group