关于 GitHub 文档
在 GitHub 上，我们努力打造准确、有价值、包容、支持辅助功能，并且易于使用的文档。
在对 GitHub Docs 贡献一份力量之前，请先花点时间让自己熟悉 GitHub 的文档理念和内容设计原则：
编写 GitHub 文档的最佳做法
无论是创建新的文章还是更新现有文章，在编写 GitHub Docs 时都应遵循以下指导准则：
内容要服务于用户需求
开始动笔之前，一定要先了解文章受众是谁、他们的目标是什么、文章将要传达的核心任务或中心思想是什么，以及要写哪种类型的内容。
确定受众
- 哪些人会阅读这篇内容？
- 他们正在尝试执行哪种操作？
确定核心用途
- 阅读本文后，受众应该能够执行什么操作或了解哪些知识？ 选择内容将会讨论到的一个或两个任务或概念。
- 如果其他任务、概念或信息并不必要，则思考如何降低其在文章中的篇幅、移至另一篇文章中，或索性全部删除。
确定内容类型
根据意图受众和内容的核心用途，确定你要编写的内容类型。 GitHub Docs 使用以下内容类型：
例如，使用概念内容类型来帮助读者了解某一个功能或主题的基本信息，以及如何帮助他们实现其目标。 使用过程内容类型来帮助人们从头至尾完成一项具体任务。
结构内容要清晰易读
使用以下最佳做法来构建内容。 将内容添加到现有文章时，请尽可能遵循现有结构。
- 提供初始上下文。 确定主题并说明其与读者的相关性。
- 按重要性和相关性，按逻辑顺序构建内容。 按照优先级顺序，以及用户将会需要的顺序放置信息。
- 句子和段落要避免过于冗长。
- 一个一个介绍概念。
- 每段使用一个想法。
- 每个句子使用一个想法。
- 强调最重要的信息。
- 以最重要的词语和要点为每句话或每个段落开篇。
- 解释概念时，先从结论开始，然后再更加详细地进行解释。 （有时，这种文章结构称为“总-分结构”。）
- 解释复杂主题的，先为读者呈现基本信息，然后在文章后面披露详细信息。
- 使用有意义的子标题。 将相关段落整理到各部分中。 为每个部分提供唯一且准确描述内容的子标题。
- 请考虑使用页面内链接来获取较长的内容。 这样，读者就可以跳转到感兴趣的区域，并跳过与其无关的内容。
编写时要考虑到可读性
让忙碌的用户能够轻松阅读和理解文本内容。
- 使用简洁朴素的语言。 尽可能使用常见、日常字词，避免行话。 开发人员熟知的术语固然有其优点，但不要认为读者知道 GitHub 的工作原理的详细信息。
- 使用主动语态。
- 简洁。
- 写简单、简洁的句子。
- 避免包含多个概念的复杂句子。
- 逐渐减少不必要的详细信息。
有关相关信息，请参阅 风格指南 和 编写要翻译的内容 中的“语气”。
格式要便于扫描
大多数读者并不会使用文章全文。 而是会_扫描_页面定位到具体信息，或_跳过_页面获取概念的主旨。
扫描或浏览内容时，读者会跳过大量文本。 他们查找与其任务相关的或是页面中显眼的元素，例如，标题、警报、列表、表格、代码块、视觉对象，以及每个部分的头几个字等。
文章明确用途和结构后，就可以运用以下格式设置技巧来优化用于扫描和一眼略过的内容。 这些技巧也有助于让内容更容易被所有读者理解。
- 使用文本突出显示（粗体和超链接等）吸引读者注意最重要的点。 请谨慎使用文本突出显示。 不要突出显示文章中总文本的 10% 以上。
- 使用格式设置元素分隔内容并在页面上留白。 例如：
- 项目符号列表（具有可选的运行子标题）
- 编号列表
- 警报
- 表
- 视觉对象
- 代码块和代码注释
延伸阅读
- "风格指南"
- “关于内容模型”
- “GitHub Docs 文章的内容”
- “可读性准则”，Content Design London
- “重写数字内容，追求简洁”，Nielsen Norman Group