关于 GitHub 文档
在 GitHub 上，我们努力打造准确、有价值、包容、支持辅助功能，并且易于使用的文档。
在对 GitHub Docs 贡献一份力量之前，请先花点时间让自己熟悉 GitHub 的文档理念、基础知识和内容设计原则：
-
[AUTOTITLE](/contributing/writing-for-github-docs/about-githubs-documentation-philosophy) -
[AUTOTITLE](/contributing/writing-for-github-docs/about-githubs-documentation-fundamentals) -
[AUTOTITLE](/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 使用以下内容类型：
-
[概念内容](/contributing/style-guide-and-content-model/conceptual-content-type) -
[参考内容](/contributing/style-guide-and-content-model/referential-content-type) -
[过程内容](/contributing/style-guide-and-content-model/procedural-content-type) -
[故障排除内容](/contributing/style-guide-and-content-model/troubleshooting-content-type) -
[快速入门](/contributing/style-guide-and-content-model/quickstart-content-type) -
[教程](/contributing/style-guide-and-content-model/tutorial-content-type)
例如，使用概念内容类型来帮助读者了解某一个功能或主题的基本信息，以及如何帮助他们实现其目标。 使用过程内容类型来帮助人们从头至尾完成一项具体任务。
将内容结构化以提高可读性
使用以下最佳做法来构建内容。 将内容添加到现有文章时，请尽可能遵循现有结构。
-
**提供初始上下文**。 确定主题并说明其与读者的相关性。 -
**按重要性和相关性，按逻辑顺序**构建内容。 按照优先级顺序，以及用户将会需要的顺序放置信息。 -
**句子和段落要避免过于冗长**。- 一个一个介绍概念。
- 每段使用一个想法。
- 每个句子使用一个想法。
-
**强调最重要的信息**。- 以最重要的词语和要点为每句话或每个段落开篇。
- 解释概念时，先从结论开始，然后再更加详细地进行解释。 有时，这种情况称为“倒金字塔结构”。
- 解释复杂主题的，先为读者呈现基本信息，然后在文章后面披露详细信息。
-
**使用有意义的子标题**。 将相关段落整理到各部分中。 为每个部分提供唯一且准确描述内容的子标题。 -
**请考虑使用页面内链接**来获取较长的内容。 这样，读者就可以跳转到感兴趣的区域，并跳过与其无关的内容。
编写时要考虑到可读性
让忙碌的用户能够轻松阅读和理解文本内容。
-
**使用简洁朴素的语言。** 尽可能使用常见、日常字词，避免行话。 开发人员熟知的术语固然有其优点，但不要认为读者知道 GitHub 的工作原理的详细信息。 -
**使用主动语态。** -
**简洁。**- 写简单、简洁的句子。
- 避免包含多个概念的复杂句子。
- 逐渐减少不必要的详细信息。
有关相关信息，请参阅 风格指南 和 编写要翻译的内容 中的“语气”。
格式要便于扫描
大多数读者并不会使用文章全文。 而是会_扫描_页面以定位具体信息，或者_浏览_页面以获取概念的大意。
扫描或浏览内容时，读者会跳过大量文本。 他们查找与其任务相关的或是页面中显眼的元素，例如，标题、警报、列表、表格、代码块、视觉对象，以及每个部分的头几个字等。
文章明确用途和结构后，就可以运用以下格式设置的技巧来优化内容以便于扫描和快速浏览。 这些技巧也有助于让内容更容易被所有读者理解。
-
**使用文本突出显示**（粗体和超链接等）吸引读者注意最重要的点。 请谨慎使用文本突出显示。 不要突出显示文章中总文本的 10% 以上。 -
**使用格式设置元素**分隔内容，并在页面上创建空白。 例如：- 项目符号列表（可选的内嵌小标题）
- 编号列表
-
[警报](/contributing/style-guide-and-content-model/style-guide#alerts) - 表
- 视觉效果
- 代码块和代码注释
其他阅读材料
-
[AUTOTITLE](/contributing/style-guide-and-content-model/style-guide) -
[AUTOTITLE](/contributing/style-guide-and-content-model/about-the-content-model) -
[AUTOTITLE](/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