我们的内容模型解释了我们在 GitHub 文档中创建的每种内容类型的目的，以及在编写或更新文章时应包含的内容。我们使用内容模型来确保我们的内容始终一致、清晰、全面地传达人们使用 GitHub 实现目标所需的信息。
我们在所有文档集中使用这些类型，以提供一致的用户体验——任何内容类型都适用于任何产品或受众。我们的内容类型会随时间演变，必要时会添加新类型。我们仅发布符合模型的内容。
一致性帮助用户形成文档的心理模型，并在他们随时间返回 GitHub 文档时，了解如何找到所需信息。保持一致的内容也更易于维护和更新，使得无论您是首次提交的开源贡献者，还是 GitHub 员工为全新产品编写文档，都能更轻松、更快速地参与文档工作。
内容结构
文档在我们的网站上被组织为多级层次结构。
- 顶层文档集
- 分类
- 映射主题
- 文章
- 文章
- 映射主题
- 文章
- 分类
组织内容需要在创建有助于用户寻找所需信息的特定分组与限制用户必须浏览的层级深度之间取得平衡。层级过深且包含大量嵌套映射主题会导致难以找到具体的文章。层级过宽、同级拥有许多分类或文章则会让用户难以评估并决定选择哪一项。
首页内容
GitHub Docs 首页，docs.github.com，突出显示人们想要查找的最重要主题。我们限制首页上的文档集合数量，以便用户能够快速找到信息，并防止首页过于拥挤、难以搜索。
首页包含所有顶层文档集以及部分分类。首页的内容围绕 GitHub 的概念和实践进行组织。例如，“CI/CD 与 DevOps”组包括 GitHub Actions、GitHub Packages 和 GitHub Pages 的顶层文档集。
将文档集添加到首页
首页的目标是帮助用户找到他们想了解的 GitHub 功能或产品信息。每添加一个条目，都会稀释其他条目的可发现性，因此我们限制首页包含的文档集合数量。
如果创建了新的顶层文档集，则将其添加到首页。
如果某个分类是使用 GitHub 产品或功能的起始点，则可以将其添加到首页。
顶层文档集
顶层文档集围绕 GitHub 产品、功能或核心工作流进行组织。所有顶层文档集都会出现在 GitHub 文档首页。仅当新文档集内容量大、包含多个可细分为映射主题的分类，并且该主题适用于多个产品、功能或账户类型时，才应创建顶层文档集。如果内容可以放入现有的任何顶层文档集，则它可能属于该已有文档集。
- 各顶层文档集的相对重要性大致相等（每个文档集都围绕某个 GitHub 产品或主要功能）。
- 大多数顶层文档集采用着陆页布局，除非出现重大例外。例如，站点政策 文档集不像其他文档集那样包含指南或操作性文章，因此不使用着陆页布局。
- 顶层文档集可以包含分类、映射主题或文章的混合。
顶层文档集的标题
- 基于功能或产品。
- 描述用户正在使用的 GitHub 哪个部分。
- 示例
分类
分类围绕一个功能或顶层文档集中与产品主题相匹配的离散任务集合进行组织。分类的主题足够细化，使其内容易于管理且不会过大而难以使用。部分分类会出现在首页。
- 分类通常从小规模开始，并随产品成长而扩展。
- 分类可以包含映射主题，以围绕更具体的用户旅程或任务细分内容。
- 使用较长的操作性文章来归组相关内容块，并保持分类内的文章简洁。
- 当分类包含超过十篇文章时，考虑将内容拆分为映射主题或额外的分类。
- 分类可以包含映射主题或文章的混合。
分类的标题
- 基于任务（以动名词开头）。
- 描述使用该功能或产品的宏观目的或目标。
- 足够通用或高层次，以适应未来的产品改进。
- 分类标题必须在 67 个字符以内，并且其
shortTitle不超过 27 个字符。 - 示例
分类简介
所有分类都应有简介。简介应为一句话，且足够通用或高层次，以适应未来的产品变化。如果对分类结构进行重大更改，请检查其简介是否需要更新。
映射主题
映射主题用于在分类中引入一个章节，将属于该分类的文章按更具体的工作流或主题进行分组，这些主题是该分类更大任务的一部分。
映射主题至少包含两篇文章。当映射主题超过八篇文章时，考虑将内容拆分为更具体的映射主题可能会更有帮助。
一般而言，除非是满足特定用户需求的最佳方式，否则避免在映射主题内部再嵌套映射主题。
映射主题的标题
- 基于任务（以动名词开头）。
- 描述其所在分类更大工作流中的更具体任务。
- 足够通用或高层次，以适应产品未来的新增内容。
- 映射主题标题必须在 63 个字符以内，并且其
shortTitle不超过 30 个字符。 - 示例
映射主题简介
所有映射主题都应有简介。简介应为一句话，且足够通用或高层次，以适应未来的产品变化。如果在映射主题中添加或删除文章，请检查其简介是否需要更新。
文章
文章是 GitHub 文档的基本内容单元——虽然我们使用多种内容类型，但它们都以文章形式发布。每种内容类型都有自己的目的、格式和结构，但我们在每种文章类型中都使用标准元素，例如简介，以确保文章提供一致的用户体验。
内容顺序
我们在分类、映射主题和文章中以可预测的方式组织内容。从适用范围最广泛到最具体、最细致或最高级别的信息，遵循以下顺序：
- 概念性内容
- 参考性内容
- 用于启用功能或设置的操作性内容
- 使用功能的操作性内容
- 管理功能或设置的操作性内容
- 禁用功能或设置的操作性内容
- 关于破坏性操作（例如删除）的操作性内容
- 故障排除信息
重复使用内容
我们使用可复用和可变的字符串，以在多个位置使用相同的内容块，例如一个操作步骤或概念段落。除非有特定原因，我们通常不会在没有必要的情况下复用整段文章。当整个章节可能在多个文章中都相关时，请先审视两者的目的。是否有机会创建一篇更长的综合文章？请参考内容模型，明确该信息的最佳永久归属位置，并在其他文章中链接到它。