# 关于内容模型

内容模型描述我们发布的内容的结构和类型。

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

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

一致性有助于人们形成文档的精神模型，并了解如何在一段时间内返回 GitHub Docs 时找到所需的信息。 维护和更新一致的内容也更加高效，这让你无论是作为开源贡献者提交第一次贡献，还是作为GitHub团队成员为一款全新的产品编写完整文档，都能更轻松、更快速地参与文档工作。

## 内容结构

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

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

组织内容需要在以下两者之间取得平衡：一是创建有助于人们找到所需内容的特定分组，二是限制人们必须导航的层级结构。 多个映射主题嵌套在一起的深层层级结构会使人们难以找到特定文章。 同一层级有许多类别或文章的宽泛层级结构会使人们难以评估和决定要选择的内容。

## 主页内容

GitHub Docs主页 [docs.github.com](/zh/enterprise-server@3.22) 突出显示了人们想要查找的最重要主题。 我们限制主页上的文档集数量，以便用户可以查找信息，并且主页不会变得过于拥挤和难以搜索。<!-- markdownlint-disable-line search-replace -->

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

### 将文档集添加到主页

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

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

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

## 顶级文档集

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

* 顶级文档集对彼此的重要性大致相同（每个文档集都以 GitHub 产品或主要功能为中心）。
* 除非存在重大异常，否则大多数顶级文档集都有登陆页面布局。 例如，“站点策略”[](/zh/site-policy)文档集不像其他文档集那样包含指南或过程性文章，因此不使用登陆页面布局。
* 顶级文档集可以包含类别、映射主题或文章的组合。

### 顶级文档集的标题

* 基于功能或产品。
* 描述某人正在使用 GitHub 的哪一部分。
* 示例
  * [组织和团队文档](/zh/enterprise-server@3.22/organizations)
  * [GitHub Issues 文档](/zh/enterprise-server@3.22/issues)

## 类别

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

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

### 类别的标题

* 基于任务（从动名词开始）。
* 描述使用功能或产品的大致用途或目标。
* 通用性或概括性，足以随着未来的产品增强功能进行缩放。
* 类别标题必须不超过 67 个字符，且 [`shortTitle`](https://github.com/github/docs/tree/main/content#shorttitle) 不超过 27 个字符。
* 示例
  * [GitHub 帐户和个人资料操作说明](/zh/enterprise-server@3.22/account-and-profile/how-tos)
  * [提交更改](/zh/enterprise-server@3.22/pull-requests/committing-changes-to-your-project)

### 类别简介

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

## 映射主题

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

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

一般情况下，避免在映射主题中嵌套映射主题，除非这是满足特定用户需求的最佳方式。

### 映射主题的标题

* 基于任务（从动名词开始）。
* 描述其所属类别的较大工作流中更具体的任务。
* 通用性或概括性，足以随着产品的未来添加进行缩放。
* 映射主题标题必须不超过 63 个字符，且 [`shortTitle`](https://github.com/github/docs/tree/main/content#shorttitle) 不超过 30 个字符。
* 示例
  * [供应链安全](/zh/enterprise-server@3.22/code-security/concepts/supply-chain-security)
  * [管理企业中的用户](/zh/enterprise-cloud@latest/admin/managing-accounts-and-repositories/managing-users-in-your-enterprise)

### 映射主题的简介

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

## 项目

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

## 内容顺序

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

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

## 重用内容

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