关于 GitHub 文档
在 GitHub，我们致力于创建准确、有价值、包容、易访问且易于使用的文档。
在为 GitHub 文档做贡献之前，请花点时间了解 GitHub 的文档理念、基本原理和内容设计原则。
GitHub 文档撰写最佳实践
无论是创建新文章还是更新已有文章，撰写 GitHub 文档时都应遵循以下指南。
使内容符合用户需求
在开始之前，了解你的读者、他们的目标、本文将涉及的核心任务或概念，以及应编写何种类型的内容非常重要。
确定受众
- 谁会阅读这些内容？
- 他们想要完成什么？
确定核心目的
- 阅读本文后，读者应能够做什么或理解什么？请选取一至两个本文将讨论的任务或概念。
- 如果还有其他非必要的任务、概念或信息，考虑是否可以放在文章后部、转移到其他文章，或完全省略。
确定内容类型
根据目标受众和内容的核心目的，确定你将撰写的内容类型。GitHub 文档使用以下内容类型：
例如，使用概念性内容类型帮助读者了解某个功能或主题的基础以及它如何帮助他们实现目标。使用操作性内容类型帮助人们从头到尾完成特定任务。
组织内容以提升可读性
使用以下最佳实践来组织内容。在向已有文章添加内容时，尽可能遵循原有结构。
- 提供初始上下文。定义主题并说明其与读者的关联。
- 按重要性和相关性以逻辑顺序组织内容。根据信息的优先级以及用户需要的顺序进行排列。
- 避免使用冗长的句子和段落.
- 逐一介绍概念。
- 每段只包含一个要点。
- 每句只表达一个要点。
- 突出最重要的信息.
- 在每个句子或段落开头使用最重要的词语和要点。
- 解释概念时，先给出结论，再进行详细说明。（这有时称为“倒金字塔”。）
- 解释复杂主题时，先向读者呈现基本信息，随后在文章后部披露细节。
- 使用有意义的小标题。将相关段落组织成章节。为每个章节提供唯一且准确描述内容的小标题。
- 考虑在较长内容中使用页面内链接。这使读者能够跳转至感兴趣的区域，跳过与其无关的内容。
编写以提升可读性
让忙碌的用户能够轻松阅读并理解文本。
- 使用简明语言。 使用常见的日常用词，尽量避免术语。对开发者熟悉的术语可以使用，但不要假设读者了解 GitHub 的工作细节。
- 使用主动语态。
- 保持简洁。
- 撰写简短且简单的句子。
- 避免包含多个概念的复杂句子。
- 删减不必要的细节。
有关相关信息，请参见《风格指南》中的“语气与风格”，以及《可翻译内容写作指南》。
格式化以适合快速浏览
大多数读者不会完整阅读整篇文章。他们要么 扫描 页面以定位特定信息，要么 略读 页面以获取概念的大致了解。
在扫描或略读内容时，读者会跳过大段文字。他们会寻找与其任务相关或在页面上突出的元素，如标题、警示、列表、表格、代码块、视觉元素以及每个章节的前几词。
在文章明确了目的和结构后，你可以使用以下格式化技巧来优化内容的扫描和略读。这些技巧也有助于提升所有读者的理解度。
- 使用文本高亮（如加粗和超链接）来强调最重要的要点。请节制使用文本高亮，文章中高亮的文字不要超过总文本的 10%。
- 使用格式化元素来分隔内容并在页面上创建空白。例如：
- 项目符号列表（可带行内子标题）
- 编号列表
- 警示框
- 表格
- 视觉元素
- 代码块和代码注释
延伸阅读
- 样式指南
- 关于内容模型
- GitHub 文档文章的内容
- 可读性指南，Content Design London
- 简化数字内容的改写，Nielsen Norman Group