关于内容模型

我们的内容模型解释了我们在 GitHub Docs 中创建的每种内容类型的目的，以及在撰写或更新文章时应包含的内容。我们使用内容模型来确保我们的内容始终如一、清晰且全面地传达人们使用 GitHub 达到目标所需的信息。

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

一致性有助于人们形成文档的心理模型，并了解如何随着时间的推移返回 GitHub Docs 时找到他们需要的信息。一致性内容的维护和更新也更有效率，无论您是进行首次提交的开源贡献者，还是 GitHub 员工编写整个新产品的文档，都更容易、更快地为文档做出贡献。

内容结构

文档在我们的网站上按多个层次结构组织。

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

主页内容

GitHub Docs 主页，docs.github.com，重点介绍了人们想要找到的最重要的主题。我们限制了主页上的文档集数量，以便人们可以找到信息，并且主页不会变得过于拥挤，难以搜索。

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

将文档集添加到主页

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

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

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

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

顶级文档集

顶级文档集围绕 GitHub 产品、功能或核心工作流进行组织。所有顶级文档集都显示在 GitHub 文档首页上。只有当有大量内容需要包含在新文档集中、多个类别被分解成地图主题，并且主题适用于所有产品、功能或帐户类型时，您才应该创建顶级文档集。如果内容可以放入任何现有的顶级文档集中，它可能属于该现有文档集。

• 顶级文档集彼此之间具有大致相同的优先级（每个文档集都以 GitHub 产品或主要功能为中心）。
• 大多数顶级文档集都具有登录页面布局，除非存在重大例外。例如，“网站政策”文档集没有像其他文档集那样的指南或程序性文章，因此它不使用登录页面布局。

顶级文档集的标题

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

类别

类别围绕顶级文档集中与产品主题一致的功能或一组离散任务进行组织。类别的主题足够狭窄，以至于其内容易于管理，并且不会增长到太大而无法使用。一些类别会显示在首页上。

• 类别通常从小开始，随着产品的发展而增长。
• 大型类别可能包含地图主题，以围绕更具体的用户旅程或任务细分内容。
• 使用长篇程序性文章来对相关内容块进行分组，并保持类别内的文章简洁。
• 当类别包含超过十篇文章时，请考虑将内容分解成地图主题或其他类别。

类别的标题

• 基于任务（以动名词开头）。
• 描述使用该功能或产品的总体目的或目标。
• 足够通用或高级，以便随着未来的产品增强而扩展。
• 类别标题必须不超过 67 个字符，并且必须具有不超过 27 个字符的 shortTitle。
• 示例
  • 在 GitHub 上设置和管理您的个人帐户
  • 将更改提交到您的项目

类别的介绍

所有类别都有介绍。介绍应只有一句话长，并且足够通用或高级，以便随着未来的产品更改而扩展。如果您大幅更改类别的结构，请检查其介绍以查看是否需要更新。

地图主题

地图主题介绍类别中的一个部分，将类别内的文章分组到更具体的工作流程或主题周围，这些工作流程或主题是类别更大任务的一部分。

地图主题包含至少三篇文章。当地图主题包含超过八篇文章时，可能需要考虑将内容分解成更具体的地图主题。

地图主题的标题

• 基于任务（以动名词开头）。
• 描述其所属类别更大工作流程中更具体的任务。
• 足够通用或高层级，以便随着产品的未来添加而扩展。
• 地图主题标题必须不超过 63 个字符，并且具有一个不超过 30 个字符的 shortTitle。
• 示例
  • 了解您的软件供应链
  • 在您的企业中管理用户

地图主题的简介

所有地图主题都有简介。简介应为一句话，并且足够通用或高层级，以便随着未来产品更改而扩展。如果您在某个地图主题中添加或删除文章，请检查其简介以查看是否需要更新。

文章

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

内容顺序

我们在类别、地图主题和文章中以可预测的方式组织内容。从最广泛的适用性到最具体、最狭窄或最高级的信息，按照以下顺序进行

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

重复使用内容

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