GitHub Docs 文章的内容

本文内容

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

“参与 GitHub Docs”部分中的文章指的是文档本身，是 GitHub 员工和开放源代码参与者的资源。

关于文章的结构

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

标有标题、简介、权限、产品标注、概念部分、过程部分和目录的文章的屏幕截图。

标题

标题充分描述了页面的内容，以及用户通过阅读页面将学到什么。

标题可能是难点。 使用这些常规准则来帮助创建清晰、有用且具有描述性的标题。 本文中每种内容类型的指南提供了更具体的标题规则。

所有内容类型的标题

  • 标题清楚地描述了页面的内容。 它们具有描述性且是具体的。
    • 使用：“浏览工作流编辑器中的操作”
    • 使用：“Codespace 配置示例”
    • 避免：“使用工作流编辑器边栏”
    • 避免：“示例”
  • 标题的长度有硬性限制，使其易于理解（并且更易于在网站上呈现）：
    • 类别标题：67 个字符，且 shortTitle 26 个字符
    • 映射主题标题：63 个字符，且 shortTitle 29 个字符
    • 文章标题：80 个字符，如果可能，60 个字符，且 shortTitle 30 个字符，最好是 20-25 个字符
  • 标题使用句首大写形式。
    • 使用：“更改提交消息”
    • 避免：“更改提交消息”
  • 同一种内容类型的标题保持一致。 请查看每种内容类型的相应规定
  • 标题为通用属性，可以随产品更改进行缩放、反映文章中的所有内容，或包含关于多个产品的内容。
    • 使用：“GitHub 的计费计划”
    • 避免：“用户和组织帐户的计费计划”
  • 标题使用一致的术语。
    • 同一个类别或类似主题中制定和遵循特定的模式。
  • 标题使用产品本身的术语。
  • 同时编写标题和简介。
    • 使用简介来拓展标题中提出的概念。
    • 如需详细信息，请参阅有关简介的指南。
  • 如果很难想出标题，请考虑内容类型。 有时，难以选择标题表示其他内容类型更适合。
  • 考虑标题如何显示在多个产品的搜索结果中。
    • 我们需要在标题或简介中包含哪些特定字词，以免人们误认为是关于其他产品的内容？
  • 考虑标题在生产环境中的外观。

产品标注

如果某个功能仅在特定产品中可用，并且仅通过版本控制无法传达该可用性，请使用产品标注。 例如，如果某个功能可用于 GHEC、GHES 和 GHAE，则只能对有关 GHEC、GHES 和 GHAE 的功能的内容进行版本控制。 如果某个功能适用于 Pro、Team、GHEC、GHES 和 GHAE（但不适用于免费版），请使用产品标注来传达该可用性。

所有产品标注都在 gated-features 中存储为可重用内容，并添加到相关文章的 YAML 前言中。

如何编写产品标注

  • 产品标注遵循严格的格式，明确标识功能以及它在哪些产品中可用。
  • 产品标注还包括“GitHub 产品”的链接，有时还包括另一篇相关文章的链接。
  • 示例：
    • [功能名称] 在 [产品] 中可用。 有关详细信息，请参阅“GitHub 的产品”。
    • [功能名称] 在 [免费产品] 的公共存储库中可用，在 [付费产品] 的公共和专用存储库中可用。 有关详细信息，请参阅“GitHub 的产品”。

包含产品标注的文章示例

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

简介

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

如何编写简介

  • 文章简介的长度是一到两个句子。
  • 映射主题和类别简介的长度是一个句子。
  • API 参考简介的长度是一个句子。
    • API 页面的简介应定义功能，使用户无需阅读整篇文章即可知道该功能是否满足其需求。
  • 简介包含页面内容的大致摘要，并更详细地形成标题中呈现的想法。
    • 在页面标题中使用易理解的字词同义词，以帮助读者以不同的方式理解文章的目的。 尽可能避免重复标题中的字词。
  • 简介是相对长久和概括的，因此它们可以随着将来对页面上内容的更改而缩放，无需频繁更新。
  • 为了便于搜索，请在简介中包括页面主题上的关键字。
  • 当简介中的术语包含我们将在文章的其他位置使用的首字母缩略词时，请指出该首字母缩略词。
  • 简介通常不包含文章中包含的任何任务的权限。

权限语句

每个过程都包含一个权限声明，说明过程中所述的操作所需的角色，这有助于人们了解他们是否能够完成任务。

有时，它与提及概念性内容中所需的权限相关，尤其是在独立概念性文章中。 请确保在相关过程中包括权限声明（或编写合并所有内容的较长文章）。

如何编写权限声明

  • 当一组权限应用于文章中的所有过程时，请使用权限前言。
  • 当一篇文章包含多个过程且应用不同的权限时，请在每个过程之前在每个相关标头下包含单独的权限声明。
  • 请勿在文章简介中包含权限。
  • 角色存在于不同的级别。 仅引用与操作位于同一级别的角色。 例如，需要拥有对存储库的管理员访问权限（存储库级别角色）才能配置受保护的分支。 可以通过成为组织所有者（组织级别角色）来获取对存储库的管理员访问权限，但存储库级别角色实际上控制你执行操作的能力，因此，它是权限声明中应提及的唯一角色。
  • 要在权限声明中使用的语言：
    • [帐户角色] 可以 [操作]。
    • 具有 [功能] 的 [功能角色] 的人可以 [操作]。
    • 避免：[帐户角色] 和具有 [功能] 的 [功能角色] 的人可以 [操作]。

权限声明的示例

工具切换器

某些文章的内容因用户用于完成任务的工具而异，例如 GitHub CLI 或 GitHub Desktop。 对于大多数内容，相同的概念或过程信息对于多个工具都是准确的。 但是，如果使信息清晰准确的唯一方法是按工具区分内容，请使用工具切换器。 请勿仅仅为了显示不同语言的示例而使用工具切换器。 仅当任务或概念根据人员使用的工具发生更改时，才使用工具切换器。 有关详细信息，请参阅“在文章中创建工具切换器”。

目录

目录会自动生成。 有关详细信息，请参阅“自动生成的微型 TOC”。

概念内容

概念性内容可帮助用户了解主题。 有关详细信息，请参阅内容模型中的“概念性内容类型”。

参考内容

参考内容提供与主动使用产品或功能相关的结构化信息。 有关详细信息，请参阅内容模型中的“参考内容类型”。

先决条件

先决条件是人们在继续执行过程之前需要知道的信息，这样他们可以在开始任务之前准备所需的一切。

如何编写先决条件

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

先决条件的标题指南

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

具有先决条件部分的文章示例

过程内容

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

故障排除内容

故障排除内容可帮助用户避免或解决错误。 有关详细信息，请参阅内容模型中的“故障排除内容类型”。

其他阅读材料

延伸阅读部分突出显示了尚未包含在文章内容或边栏中的其他目标文章。 如果延伸阅读部分提供实际价值，请慢慢使用它。

如何编写延伸阅读部分

  • 使用项目符号列表。
  • 如果延伸阅读部分提供实际价值，请慢慢使用它 - 有关链接的指南，请参阅样式指南。

延伸阅读部分的标题和格式

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