关于内容模型

我们的内容模型解释了我们在 GitHub Docs 中创建的每种类型的内容的用途，以及当你撰写或更新文章时要包含的内容。 我们使用内容模型来确保我们的内容使用 GitHub 一致、清晰、全面地传达人们实现其目标所需的信息。

我们在所有文档集中使用这些类型来提供一致的用户体验 - 任何内容类型都适用于任何产品或受众。 我们的内容类型会随时间推移而变化，我们根据需要添加新类型。 我们只发布遵循模型的内容。

一致性可帮助人们形成文档的心智模型，并了解如何在一段时间内返回到 GitHub Docs 时找到所需的信息。 维护和更新一致内容也更高效，这样，无论你是首次提交文档的开放源代码参与者，还是记录全新产品的 GitHub 工作人员中的编写者，都能够更轻松、更快地参与文档。

内容结构

文档在我们的网站上分为多个层次结构级别。

• 顶级文档集
  • 类别
    • 映射主题
      • 文章
    • 文章
  • 文章

组织内容可在进行特定分组（帮助人们找到他们正在搜索的内容）和限制人们必须浏览的层次结构层级之间取得平衡。 许多映射主题嵌套在一起的深层层次结构可能会使查找特定文章变得困难。 同一级别有许多类别或文章的广泛层次结构使人们难以评估和决定他们想要选择什么。

主页内容

GitHub Docs 主页 docs.github.com 突出显示了人们想要查找的最重要主题。 我们限制主页上的文档集数量，以便用户可以查找信息，并且主页不会变得过于拥挤和难以搜索。

主页包括所有顶级文档集和某些类别。 主页上的内容围绕 GitHub 的概念和做法进行组织。 例如，“CI/CD 和 DevOps”组包括 GitHub Actions、GitHub Packages 和 GitHub Pages 的顶级文档集。

将文档集添加到主页

主页的目的是帮助用户查找有关他们想要了解的 GitHub 功能或产品的信息。 添加到主页的每个项目都会稀释其他每个项目的可发现性，因此我们限制主页中包含的文档集数。

如果创建新的顶级文档集，则会将其添加到主页。

如果类别作为使用 GitHub 产品或功能的起点，则可以将其添加到主页。

例如，在主页上的“安全性”分组下，除了代码安全性顶级文档集外，还包含供应链安全、安全公告、Dependabot、Code scanning 和 Secret scanning类别，因为这些类别中的每个类别都是 GitHub 产品和功能的入口点。 主页中未包含安全概述，因为它提供了有关使用代码安全产品的其他信息，不是产品或功能的介绍。

顶级文档集

顶级文档集围绕 GitHub 产品、功能或核心工作流进行组织。 所有顶级文档集都显示在 GitHub Docs 主页上。 仅当新文档集中包含大量内容，多个类别分解为映射主题以及主题跨产品、功能或帐户类型应用时，才应创建顶级文档集。 如果内容可以容纳在任何现有顶级文档集中，则它可能属于该现有文档集。

• 各个顶级文档集的重要性大致相同（每个文档集都以 GitHub 产品或主要功能为中心）。
• 除非存在重大异常，否则大多数顶级文档集都有登陆页面布局。 例如，网站策略文档集没有与其他文档集一样的指导或过程文章，因此它不使用登陆页面布局。
• 顶级文档集可以包含类别、地图主题或文章的组合。

顶级文档集的标题

• 基于功能或产品。
• 描述某人使用的 GitHub 部分。
• 示例
  • 组织和团队文档
  • GitHub Issues 文档

类别

类别围绕与产品主题一致的顶级文档集中的功能或一组离散任务进行组织。 类别的主题足够窄，这样其内容是可管理的，并且不会变得太大而无法使用。 某些类别显示在主页上。

• 类别通常开始较小，然后随着产品增大。
• 类别可能包含映射主题，用于围绕更具体的用户旅程或任务细分内容。
• 使用长程序文章对相关内容块进行分组，并使类别中的文章保持简化。
• 当类别包含超过 10 篇文章时，请考虑将内容分解为映射主题或其他类别。
• 类别可以包含映射主题或文章的组合。

类别的标题

• 基于任务（从动名词开始）。
• 描述使用功能或产品的大致用途或目标。
• 通用性或概括性，足以随着未来的产品增强功能进行缩放。
• 类别标题不能超过 67 个字符，并且 shortTitle 必须少于 27 个字符。
• 示例
  • 设置和管理 GitHub 上的个人帐户
  • 将更改提交到项目

类别简介

所有类别都有简介。 简介的长度应该是一个句子，并且通用性和概括性足以随着未来的产品更改进行缩放。 如果显著更改了类别的结构，请检查其简介以获取所需的更新。

映射主题

映射主题介绍类别的一个部分，围绕更具体的工作流或属于该类别较大任务的一部分的主题对类别中的文章分组。

映射主题至少包含两篇文章。 当映射主题包含超过 8 篇文章时，考虑将内容分解为更具体的映射主题可能会很有用。

一般来说，除非这是满足特定用户需求的最佳方式，否则应避免在映射主题中包含映射主题。

映射主题的标题

• 基于任务（从动名词开始）。
• 描述其所属类别的较大工作流中更具体的任务。
• 通用性或概括性，足以随着产品的未来添加进行缩放。
• 映射主题标题不能超过 63 个字符，并且 shortTitle 必须少于 30 个字符。
• 示例
  • 了解您的软件供应链
  • 管理企业中的用户

映射主题的简介

所有映射主题都有简介。 简介的长度应该是一个句子，并且通用性和概括性足以随着未来的产品更改进行缩放。 如果在映射主题中添加或删除文章，请检查其简介以获取所需的更新。

项目

文章是 GitHub Docs 的基本内容单位，虽然我们使用多种内容类型，但它们都作为文章发布。 每种内容类型都有自己的用途、格式和结构，但我们在每个文章类型（如简介）中使用标准元素，以确保文章提供一致的用户体验。

内容顺序

我们会在类别、映射主题和文章中可预测地组织内容。 从最广泛的适用性到最具体、最窄或最高级的信息，请遵循以下顺序：

• 概念内容
• 参考内容
• 用于启用功能或设置的过程内容
• 关于使用功能的过程内容
• 关于管理功能或设置的过程内容
• 关于禁用功能或设置的过程内容
• 关于破坏性操作（例如删除）的过程内容
• 故障排除信息

重用内容

我们使用可重用的和可变的字符串在多个位置使用相同的内容块，例如过程步骤或概念段落。 我们通常不会在没有特定原因的情况下重复使用文章的大部分。 如果某篇文章的整个部分可能与多篇文章相关，请查看两者的用途。 是否有机会创建一篇长篇文章？ 请参阅内容模型，以阐明信息的最佳永久主页，并从另一篇文章链接到它。