文档风格指南

本页面提供了 Kubernetes 文档的写作风格指南。这些是指南，不是规则。请自行判断，并随时通过 pull request 提出对本文件的修改建议。

有关为 Kubernetes 文档创建新内容的更多信息，请阅读《文档内容指南》。

风格指南的更改由 SIG Docs 作为一个整体进行。要提议更改或添加内容，请将其添加到即将举行的 SIG Docs 会议议程中，并参加会议以参与讨论。

语言

Kubernetes 文档已被翻译成多种语言（参见本地化 README）。

为不同语言本地化文档的方法在《本地化 Kubernetes 文档》中有描述。

英文文档使用美式英语拼写和语法。

文档格式标准

API 对象使用大驼峰式命名（Upper Camel Case）

当您专门提及与 API 对象交互时，请使用 大驼峰式命名（UpperCamelCase），也称为 Pascal 命名。您可能会在 API 参考中看到不同的写法，例如“configMap”。在撰写一般性文档时，最好使用大驼峰式命名，称之为“ConfigMap”。

当您一般性地讨论 API 对象时，请使用句子风格大小写。

以下示例着重于大小写。有关格式化 API 对象名称的更多信息，请参阅有关代码风格的相关指南。

占位符使用尖括号

占位符使用尖括号。告知读者占位符代表什么，例如

显示 Pod 信息

kubectl describe pod <pod-name> -n <namespace>

如果 Pod 的命名空间是 default，则可以省略 '-n' 参数。

用户界面元素使用粗体

斜体用于定义或介绍新术语

文件名、目录和路径使用代码风格

在引号内使用国际标点符号标准

行内代码格式化

行内代码、命令使用代码风格

对于 HTML 文档中的行内代码，请使用 <code> 标签。在 Markdown 文档中，请使用反引号 (`)。但是，API kinds（如 StatefulSet 或 ConfigMap）则按原样编写（无反引号）；这允许使用所有格撇号。

对象字段名和命名空间使用代码风格

Kubernetes 命令工具和组件名称使用代码风格

以组件工具或组件名称开头句子

使用通用描述符代替组件名称

字符串和整数字段值使用普通样式

对于字符串或整数类型的字段值，请使用普通样式，不带引号。

然而，如果可能引起读者混淆，请考虑给值加上引号，例如将其与 API kind 混淆。

引用 Kubernetes API 资源

本节讨论如何在文档中引用 API 资源。

关于“资源”的澄清

Kubernetes 使用“resource”一词来指代 API 资源。例如，URL 路径 /apis/apps/v1/namespaces/default/deployments/my-app 代表 "default"命名空间中名为 "my-app" 的 Deployment。在 HTTP 术语中，namespace 就是一种资源——就像所有 Web URL 都标识一个资源一样。

Kubernetes 文档也使用“resource”来讨论 CPU 和内存的请求与限制。通常最好将 API 资源称为“API resources”；这有助于避免与 CPU 和内存资源或与其他类型的资源混淆。

如果您使用的是资源名称的小写复数形式，例如 deployments 或 configmaps，请提供额外的书面上下文以帮助读者理解您的意思。如果您在可以使用大驼峰式名称的上下文中使用了该术语，并且存在歧义的风险，请考虑使用大驼峰式名称的 API kind。

何时使用 Kubernetes API 术语

不同的 Kubernetes API 术语是

• API kinds：API URL 中使用的名称（例如 pods、namespaces）。API kinds 有时也称为resource types。
• API resource：API kind 的单个实例（例如 pod、secret）。
• Object：用作“意图记录”的资源。对象是您集群特定部分的期望状态，Kubernetes 控制平面会尝试维护。Kubernetes API 中的所有对象也都是资源。

为清晰起见，您可以在引用 Kubernetes 文档中的 API 资源时添加“resource”或“object”。例如：写“a Secret object”而不是“a Secret”。如果仅从大小写就能清楚，则无需添加额外的词。

当更改有助于避免误解时，请考虑重新措辞。一种常见的情况是当您想以 API kind 开头一个句子时，例如“Secret”；因为英语和其他语言在句子开头都会大写，所以读者无法区分您是指 API kind 还是通用概念。改写可以提供帮助。

API 资源名称

始终使用 大驼峰式命名（UpperCamelCase）（也称为 PascalCase）来格式化 API 资源名称。请勿使用代码格式来编写 API kinds。

不要将 API 对象名称拆分成单独的单词。例如，使用 PodTemplateList，而不是 Pod Template List。

有关 PascalCase 和代码格式的更多信息，请参阅有关API 对象使用大驼峰式命名和行内代码、命令和 API 对象使用代码风格的相关指南。

有关 Kubernetes API 术语的更多信息，请参阅有关Kubernetes API 术语的相关指南。

代码片段格式

不要包含命令提示符

分离命令和输出

验证 Pod 是否在你选择的节点上运行。

kubectl get pods --output=wide

输出类似于：

NAME     READY     STATUS    RESTARTS   AGE    IP           NODE
nginx    1/1       Running   0          13s    10.200.0.4   worker0

版本化 Kubernetes 示例

包含版本信息的代码示例和配置示例应与伴随文本保持一致。

如果信息是特定于版本的，则 Kubernetes 版本需要在任务模板或教程模板的prerequisites部分进行定义。页面保存后，prerequisites部分将显示为Before you begin。

要指定任务或教程页面的 Kubernetes 版本，请在页面的 front matter 中包含 min-kubernetes-server-version。

如果示例 YAML 位于独立文件中，请查找并审查包含它的主题作为参考。验证使用独立 YAML 的任何主题是否已定义适当的版本信息。如果独立 YAML 文件未被任何主题引用，请考虑删除它而不是更新它。

例如，如果您正在编写与 Kubernetes 版本 1.8 相关的教程，您的 markdown 文件的 front-matter 应如下所示

---
title: <your tutorial title here>
min-kubernetes-server-version: v1.8
---

在代码和配置示例中，请勿包含有关其他版本的注释。请注意不要在您的示例中包含不正确的陈述作为注释，例如

apiVersion: v1 # earlier versions use...
kind: Pod
...

公式和方程

您可以使用 Docsy 对图表和公式的支持。

例如：\\(\frac{7}{9} \sqrt{K^8 s}\\)，渲染为 \(\frac{7}{9} \sqrt{K^8 s}\)。

如果合理，请优先使用行内公式，但如果可能有助于读者理解，您可以使用 math 块。

阅读 Docsy 指南，了解您需要更改页面中的哪些内容来激活支持；如果您遇到问题，请将 math: true 添加到页面的front matter中（即使您认为自动激活应该足够了，也可以这样做）。

Kubernetes.io 词汇表

一份 Kubernetes 特定术语和单词列表，应在整个站点中保持一致使用。

短代码（Shortcodes）

Hugo Shortcodes 有助于创建不同层次的修辞吸引力。我们的文档在此类别中支持三种不同的短代码：Note {{< note >}}，Caution {{< caution >}}，和 Warning {{< warning >}}。

1. 将文本用打开和关闭的短代码括起来。

2. 使用以下语法应用样式

   {{< note >}}
   No need to include a prefix; the shortcode automatically provides one. (Note:, Caution:, etc.)
   {{< /note >}}
   

   输出为：

   注意

   您选择的前缀与标签的文本相同。

注意

使用 {{< note >}} 来突出显示提示或可能有助于了解的信息。

例如

{{< note >}}
You can _still_ use Markdown inside these callouts.
{{< /note >}}

输出为：

您可以在列表中使用 {{< note >}}

1. Use the note shortcode in a list

1. A second item with an embedded note

   {{< note >}}
   Warning, Caution, and Note shortcodes, embedded in lists, need to be indented four spaces. See [Common Shortcode Issues](#common-shortcode-issues).
   {{< /note >}}

1. A third item in a list

1. A fourth item in a list

输出为：

1. 在列表中使用 note 短代码

2. 包含嵌入式 note 的第二个项目

   注意

   Warning, Caution, and Note shortcodes, embedded in lists, need to be indented four spaces. See [Common Shortcode Issues](#common-shortcode-issues).
   

3. 列表中的第三项

4. 列表中的第四项

注意

使用 {{< caution >}} 来引起注意重要的信息，以避免陷阱。

例如

{{< caution >}}
The callout style only applies to the line directly above the tag.
{{< /caution >}}

输出为：

警告

使用 {{< warning >}} 来指示危险或必须遵循的信息。

例如

{{< warning >}}
Beware.
{{< /warning >}}

输出为：

常见的短代码问题

有序列表

短代码会中断编号列表，除非您在通知和标签前缩进四个空格。

例如

1. Preheat oven to 350˚F

1. Prepare the batter, and pour into springform pan.
   {{< note >}}Grease the pan for best results.{{< /note >}}

1. Bake for 20-25 minutes or until set.

输出为：

1. 烤箱预热至 350˚F

2. 准备面糊，倒入弹簧扣烤盘。

   注意

   给烤盘涂油以获得最佳效果。

3. 烘烤 20-25 分钟或直至凝固。

包含语句

包含语句中的短代码会破坏构建。您必须将其插入父文档中，在调用 include 之前和之后。例如

{{< note >}}
{{< include "task-tutorial-prereqs.md" >}}
{{< /note >}}

Markdown 元素

换行

使用单个换行来分隔块级内容，如标题、列表、图像、代码块等。例外情况是二级标题，应使用两个换行。二级标题紧跟在一级标题（或标题）之后，前面没有任何段落或文本。双倍行距有助于在代码编辑器中更好地可视化内容的整体结构。

在 Markdown 源中适当地手动换行段落。由于 git 工具和 GitHub 网站逐行生成文件 diff，手动换行长行有助于审阅者轻松找出 PR 中所做的更改并提供反馈。它还有助于下游本地化团队，因为人们会逐行跟踪上游更改。换行可以在句末或标点符号处发生。一个例外是 Markdown 链接或短代码应保持在一行。

标题和副标题

访问此文档的读者可能会使用屏幕阅读器或其他辅助技术（AT）。屏幕阅读器是线性输出设备，它们一次输出页面上的一个项目。如果页面内容很多，您可以使用标题为页面提供内部结构。良好的页面结构有助于所有读者轻松导航页面或筛选感兴趣的主题。

段落

链接

列表

将列表中相互关联且需要按特定顺序出现或指示多个项目之间相关性的项目分组。当屏幕阅读器遇到列表时——无论是有序列表还是无序列表——它会向用户宣布有一个列表项组。然后用户可以使用箭头键在列表中的各个项目之间上下移动。网站导航链接也可以标记为列表项；毕竟它们只是相关链接的集合。

• 如果列表中的一个或多个项目是完整的句子，则在列表项末尾加上句点。为了保持一致性，通常所有项目都应该是完整的句子，或者都不是。

  注意

  作为不完整介绍性句子一部分的有序列表可以小写，并像每个项目都是介绍性句子的一部分一样进行标点。

• 有序列表使用数字一（1.）。

• 无序列表使用（+）、（*）或（-）。

• 在每个列表项后留一个空行。

• 使用四个空格缩进嵌套列表（例如，⋅⋅⋅⋅）。

• 列表项可能包含多个段落。列表项中的每个后续段落都必须缩进四个空格或一个制表符。

表

数据表的语义目的是呈现表格数据。视力正常的用户可以快速扫描表格，但屏幕阅读器会逐行读取。表格标题用于为数据表创建描述性标题。辅助技术（AT）使用 HTML 表格标题元素在页面结构中向用户识别表格内容。

• 使用 Hugo 表格短代码添加表格标题。

内容最佳实践

本节包含关于清晰、简洁和一致内容的建议最佳实践。

使用现在时

例外：如果需要传达正确的含义，请使用将来时或过去时。

使用主动语态

例外：如果主动语态会导致笨拙的结构，请使用被动语态。

使用简单直接的语言

使用简单直接的语言。避免使用不必要的短语，例如说“请”。

将读者称为“您”

避免使用拉丁语

优先使用英语术语而非拉丁缩写。

例外：使用 "etc." 表示 et cetera。

要避免的模式

避免使用“我们”

在句子中使用“我们”可能会令人困惑，因为读者可能不知道他们是否属于您所描述的“我们”。

避免使用行话和习语

一些读者以英语为第二语言。避免使用行话和习语，以帮助他们更好地理解。

避免关于未来的陈述

避免做出承诺或暗示未来。如果您需要谈论 alpha 功能，请将文本放在一个将它标识为 alpha 信息的标题下。

此规则的一个例外是关于宣布的已弃用项，旨在在未来版本中移除的文档。例如，已弃用的 API 迁移指南。

避免使用过时的陈述

避免使用“目前”和“新”等词。今天的新功能可能在几个月后就不再被认为是新的了。

避免使用假设特定理解水平的词语

避免使用“仅仅”、“简单”、“容易”等词。这些词没有增加价值。

EditorConfig 文件

Kubernetes 项目维护了一个 EditorConfig 文件，该文件在 VS Code 等文本编辑器中设置了通用的样式偏好。如果您想确保您的贡献与项目的其他部分保持一致，可以使用此文件。要查看该文件，请参阅仓库根目录中的.editorconfig。

下一步

• 了解如何编写新主题。
• 了解如何使用页面模板。
• 了解自定义 hugo 短代码。
• 了解如何创建 pull request。