GitHub Docs 文章的内容

每篇文章都包含一些标准元素，并且可能包含条件或可选元素。我们还使用文章中内容的标准顺序。

本文内容

关于文章的结构

在文章中，内容部分的顺序是标准的。每篇文章都包含必需的元素。文章还将包含内容设计或创建中概述的条件元素和可选元素。有关更多详细信息，请参阅以下指南。

Screenshot of article with title, intro, permissions, product callout, conceptual section, procedural section, and table of contents labeled.

标题

标题完整地描述了页面内容，以及读者通过阅读页面可以学到什么。

标题可能很具有挑战性。使用以下一般指南来帮助创建清晰、有用和描述性的标题。本文中每种内容类型的指南提供了更具体的标题规则。

所有内容类型的标题

  • 标题清楚地描述了页面内容。它们具有描述性和特异性。
    • 使用：“在工作流编辑器中浏览操作”
    • 使用："配置代码空间的示例"
    • 避免："使用工作流编辑器侧边栏"
    • 避免："示例"
  • 标题的长度有严格限制，以确保易于理解（并更易于在网站上呈现）
    • 类别标题：67 个字符，shortTitle 26 个字符
    • 地图主题标题：63 个字符，shortTitle 29 个字符
    • 文章标题：80 个字符，如果可能，60 个字符，shortTitle 30 个字符，理想情况下为 20-25 个字符
  • 标题使用句子大小写。
    • 使用："更改提交消息"
    • 避免："更改提交消息"
  • 标题在整个内容类型中保持一致。请参阅每种内容类型的具体指南。
  • 标题足够通用，可以随着产品变化而扩展，反映文章中的所有内容，或包含多个产品的内容。
    • 使用："GitHub 的计费计划"
    • 避免："用户和组织帐户的计费计划"
  • 标题使用一致的术语。
    • 在类别或类似主题中开发和遵循模式。
  • 标题使用产品本身的术语。
  • 同时编写标题和简介。
    • 使用简介来发展标题中提出的想法。
    • 有关更多信息，请参阅有关 简介 的指南。
  • 如果难以想出标题，请考虑内容类型。有时难以选择标题表明另一种内容类型更适合。
  • 考虑标题在多个产品的搜索结果中将如何显示。
    • 我们需要在标题或简介中包含哪些特定词语，以避免人们将其误认为是关于其他产品的內容？
  • 考虑标题在生产环境中的外观。

简介

每个页面的顶部都有一个简介，提供上下文并设定预期，使读者能够快速判断页面是否与他们相关。简介还会显示在搜索结果中，以提供上下文信息，帮助读者选择结果。

如何编写简介

  • 文章简介为一到两句话。
  • 地图主题和类别简介为一句话。
  • API 参考简介为一句话。
    • API 页面的简介应定义功能，以便用户无需阅读整篇文章即可了解该功能是否满足他们的需求。
  • 引言包含页面内容的高级摘要，以更详细的方式阐述标题中提出的想法。
    • 使用页面标题中词语的通俗同义词，帮助读者从不同的角度理解文章的目的。尽可能避免重复标题中的词语。
  • 引言相对常青且高级，因此可以随着页面内容的未来变化而扩展，无需频繁更新。
  • 为了可搜索性，在引言中包含页面主题的关键词。
  • 如果引言中的术语在文章的其他地方使用缩略语，请标明缩略语。
  • 引言通常不包含文章中任何任务的权限。

权限声明

每个步骤都包含一个权限声明，解释执行步骤中描述的操作所需的权限，这有助于人们了解他们是否能够完成任务。

偶尔，在概念性内容中提及所需的权限是相关的，尤其是在独立的概念性文章中。确保在相关步骤中也包含权限声明（或编写一篇更长的文章，将所有内容结合在一起）。

如何编写权限声明

  • 当一组权限适用于文章中的所有步骤时，请使用权限前置信息。
  • 当文章包含多个步骤并且不同的权限适用时，在每个相关标题下，每个步骤之前，包含一个单独的权限声明。
  • 不要在文章的引言中包含权限。
  • 角色存在于不同的级别。只引用与操作相同级别的角色。例如，您需要对存储库（存储库级角色）具有管理员访问权限才能配置受保护的分支。您可以通过成为组织所有者（组织级角色）来获得对存储库的管理员访问权限，但存储库级角色实际上控制您执行操作的能力，因此这是权限声明中唯一应该提到的角色。
  • 权限声明中使用的语言
    • [帐户角色] 可以 [操作]。
    • 具有 [功能角色] 访问权限的人员可以 [操作] [功能]。
    • 避免：拥有 [ACCOUNT ROLE] 权限和 [FEATURE ROLE] 功能访问权限的用户可以 [ACTION]。

权限语句示例

产品说明

当一项功能仅在特定产品中可用，并且仅通过版本控制无法传达该可用性时，请使用产品说明。例如，如果一项功能可用于 GHEC 和 GHES，您可以仅针对 GHEC 和 GHES 版本化有关该功能的内容。如果一项功能可用于 Pro、Team、GHEC 和 GHES（但不适用于 Free），请使用产品说明来传达该可用性。

所有产品说明都存储在 gated-features 中，并添加到相关文章的 YAML 前置信息中。

如何编写产品说明

  • 产品说明遵循严格的格式，明确标识功能及其可用的产品。
  • 产品说明还包含指向“GitHub 产品”的链接，有时还会指向其他相关文章。
  • 示例
    • [功能名称] 在 [产品(s)] 中可用。有关更多信息，请参阅“GitHub 产品”。
    • [功能名称] 在使用 [免费产品(s)] 的公共仓库中可用，在使用 [付费产品] 的公共和私有仓库中可用。有关更多信息，请参阅“GitHub 产品”。

包含产品说明的文章示例

检查源文件和 gated-features 以了解源内容的编写方式。

工具切换器

某些文章的内容会根据用户完成任务所使用的工具（例如 GitHub CLI 或 GitHub Desktop）而有所不同。对于大多数内容，相同概念或程序信息对于多种工具来说都是准确的。但是，如果只有通过工具区分内容才能使信息清晰准确，请使用工具切换器。不要仅仅为了展示不同语言的示例而使用工具切换器。仅当任务或概念根据用户使用的工具而改变时，才使用工具切换器。有关更多信息，请参阅“在文章中创建工具切换器”。

目录

目录是自动生成的。有关更多信息，请参阅“自动生成的迷你目录”。

概念性内容

概念性内容帮助人们理解或学习某个主题。有关更多信息，请参阅内容模型中的“概念性内容类型”。

参考性内容

参考性内容提供与积极使用产品或功能相关的结构化信息。有关更多信息，请参阅内容模型中的“参考性内容类型”。

先决条件

先决条件是人们在继续执行某个过程之前需要了解的信息，以便他们在开始任务之前准备所有必需的物品。

如何编写先决条件

  • 在过程的编号步骤之前立即编写先决条件。
  • 可以使用列表、句子或段落来解释先决条件。
  • 也可以在以下情况下使用单独的先决条件部分：
    • 先决条件信息非常重要，不能错过。
    • 存在多个先决条件。
  • 为了重复或突出显示有关数据丢失或破坏性操作的重要信息，也可以使用警告或危险提示来共享先决条件。

先决条件标题指南

  • 使用单独的部分时，请使用名为 Prerequisites 的标题。

包含先决条件部分的文章示例

过程性内容

过程性内容帮助人们完成任务。有关更多信息，请参阅内容模型中的“过程性内容类型”。

故障排除内容

故障排除内容帮助人们避免或解决错误。有关更多信息，请参阅内容模型中的“故障排除内容类型”。

后续步骤

当文章描述了大型流程中的一个步骤，或者有一个大多数人想要执行的逻辑下一步时，请包含一个“下一步”部分。您可以将用户链接到文章或其他 GitHub 资源。

“下一步”部分示例

## Next steps

- You can monitor self-hosted runners and troubleshoot common issues. See "Monitoring and troubleshooting self hosted runners."

- GitHub recommends that you review security considerations for self-hosted runner machines. See "Security hardening for GitHub Actions."

在本例中，来自“为您的企业开始使用自托管运行器”的“下一步”部分包含指向用户在开始使用文章中描述的功能后需要执行的步骤的链接。

## Next steps

After your enterprise account is created, we recommend learning more about how enterprise accounts work and configuring settings and policies. Follow the "Get started with your enterprise account" learning path.

在本例中，来自“创建企业帐户”的“下一步”部分链接到大多数刚完成创建企业帐户的用户想要访问的下一个位置。

进一步阅读

如果有其他文章可以帮助用户完成其任务或学习使用当前文章中描述的主题，请将它们包含在“进一步阅读”部分中。仅包含尚未在文章内容中链接的文章的链接。

仅包含帮助用户完成当前任务或主题的链接。专注并为用户提供有价值的资源比提供所有可能的链接更好。

使用无序列表格式化“进一步阅读”部分。有关如何编写链接，请参阅“样式指南”。

“进一步阅读”部分的标题和格式

## Further reading
- "[Article title](article-URL)"
- [External resource title](external-resource-URL) in External Resource Name