文档风格指南

此页面提供 Kubernetes 文档的写作风格指南。 这些是指导原则，而不是规则。 请运用你的最佳判断，并随时在拉取请求中提出对本文档的修改建议。

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

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

语言

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

在 本地化 Kubernetes 文档 中描述了如何将文档本地化为不同语言。

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

文档格式标准

API 对象使用大驼峰命名法

当您专门提到与 API 对象交互时，请使用大驼峰命名法，也称为 Pascal 命名法。 您可能会在API 参考中看到不同的首字母大写，例如 “configMap”。 在编写通用文档时，最好使用大驼峰命名法，将其称为 “ConfigMap”。

当您一般讨论 API 对象时，请使用句子式首字母大写。

以下示例侧重于首字母大写。 有关格式化 API 对象名称的更多信息，请查看有关 代码样式的相关指导。

占位符使用尖括号

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

显示有关 pod 的信息

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

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

用户界面元素使用粗体

使用斜体定义或引入新术语

文件名、目录和路径使用代码样式

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

内联代码格式

内联代码和命令使用代码样式

对于 HTML 文档中的内联代码，请使用 <code> 标记。 在 Markdown 文档中，使用反引号 (`)。 但是，StatefulSet 或 ConfigMap 等 API 类型按原样书写（没有反引号）； 这样可以使用所有格撇号。

对象字段名称和命名空间使用代码样式

Kubernetes 命令工具和组件名称使用代码样式

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

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

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

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

但是，如果读者可能将该值与 API 种类混淆，请考虑使用引号。

引用 Kubernetes API 资源

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

关于“资源”的澄清

Kubernetes 使用术语 *resource* 来指代 API 资源。例如，URL 路径 /apis/apps/v1/namespaces/default/deployments/my-app 表示在 “default” 命名空间 中名为 “my-app” 的 Deployment。在 HTTP 术语中，命名空间 是一种资源 - 所有 Web URL 标识资源的方式相同。

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

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

何时使用 Kubernetes API 术语

不同的 Kubernetes API 术语是

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

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

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

API 资源名称

始终使用 UpperCamelCase（也称为 PascalCase）格式化 API 资源名称。不要使用代码格式编写 API 种类。

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

有关 PascalCase 和代码格式的更多信息，请查看关于对 API 对象使用 Upper Camel Case 和 对内联代码、命令和 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 示例的版本控制

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

如果信息是特定于版本的，则需要在任务模板或教程模板的 prerequisites 部分中定义 Kubernetes 版本。保存页面后，prerequisites 部分将显示为 **开始之前**。

要为任务或教程页面指定 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
...

Kubernetes.io 词汇表

在整个站点中一致使用的 Kubernetes 特定术语和单词列表。

Shortcodes

Hugo Shortcodes 有助于创建不同的修辞吸引力级别。我们的文档支持此类别中的三个不同的 shortcode：Note {{< note >}}、Caution {{< caution >}} 和 Warning {{< warning >}}。

1. 用开始和结束 shortcode 包围文本。

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 shortcode

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 >}}

输出是

常见的 Shortcode 问题

有序列表

除非您在通知和标签之前缩进四个空格，否则 Shortcode 将中断编号列表。

例如

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 分钟或直至凝固。

包含语句

包含语句内的 Shortcode 将会中断构建。您必须在调用 include 之前和之后将它们插入到父文档中。例如

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

Markdown 元素

换行符

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

在适当的时候，手动换行 Markdown 源中的段落。由于 git 工具和 GitHub 网站逐行生成文件差异，手动换行长行有助于审阅者轻松找出 PR 中所做的更改并提供反馈。它还有助于下游本地化团队，这些团队会逐行跟踪上游更改。换行可以在句子末尾或标点符号字符处进行。此规则的一个例外是 Markdown 链接或 shortcode 应位于单行中。

标题和题目

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

段落

链接

列表

将彼此相关且需要按特定顺序显示或表示多个项目之间关联的项目分组到一个列表中。当屏幕阅读器遇到列表时（无论是顺序列表还是无序列表），它都会向用户声明存在一组列表项。然后，用户可以使用箭头键在列表中的各个项目之间上下移动。网站导航链接也可以标记为列表项；毕竟它们只是一组相关的链接。

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

  注意

  作为不完整引导句一部分的有序列表可以使用小写字母，并且像每个项目都是引导句的一部分一样进行标点。

• 对于有序列表，请使用数字一 (1.)。

• 对于无序列表，请使用 (+)、(*) 或 (-)。

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

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

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

表格

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

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

内容最佳实践

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

使用现在时

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

使用主动语态

例外：如果主动语态导致表达笨拙，请使用被动语态。

使用简单直接的语言

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

将读者称为“您”

避免使用拉丁语短语

优先使用英语术语，而不是拉丁语缩写。

例外：将 "etc." 用于 et cetera。

要避免的模式

避免使用“我们”

在句子中使用“我们”可能会造成混淆，因为读者可能不知道他们是否是您描述的“我们”的一部分。

避免使用行话和习语

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

避免有关未来的陈述

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

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

避免使用很快就会过时的陈述

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

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

避免使用诸如“只是”、“简单”、“容易”或“轻易”之类的词。这些词不会增加价值。

EditorConfig 文件

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

下一步

• 了解有关编写新主题的信息。
• 了解有关使用页面模板的信息。
• 了解有关自定义 hugo 短代码的信息。
• 了解有关创建拉取请求的信息。