文档样式指南

本页面提供了 Kubernetes 文档的写作风格指南。这些是指南，而不是规则。请您做出最佳判断，并随时通过拉取请求提出对本文档的更改。

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

样式指南的更改由 SIG Docs 小组共同制定。要提出更改或添加内容，请将其添加到议程中，以便在即将召开的 SIG Docs 会议上进行讨论，并参加会议参与讨论。

语言

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

本地化 Kubernetes 文档中描述了如何将文档本地化为其他语言。

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

文档格式标准

对 API 对象使用大驼峰命名法

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

当您一般性地讨论 API 对象时，请使用句子样式 capitalization。

以下示例侧重于 capitalization。有关格式化 API 对象名称的更多信息，请查看代码样式中的相关指南。

对占位符使用尖括号

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

显示有关 Pod 的信息

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

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

对用户界面元素使用粗体

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

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

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

内联代码格式

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

对于 HTML 文档中的内联代码，请使用 <code> 标记。在 Markdown 文档中，请使用反引号 (`)。但是，API 类型（例如 StatefulSet 或 ConfigMap）应按字面意思编写（不使用反引号）；这允许使用所有格撇号。

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

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

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

使用通用描述符而不是组件名称

对字符串和整数字段值使用正常样式

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

但是，如果读者有可能将值与 API 类型混淆，请考虑将值用引号括起来。

引用 Kubernetes API 资源

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

澄清“资源”的含义

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

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

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

何时使用 Kubernetes API 术语

不同的 Kubernetes API 术语包括：

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

为清楚起见，您可以在 Kubernetes 文档中引用 API 资源时添加“资源”或“对象”。例如，写“Secret 对象”而不是“Secret”。如果 capitalization 已经很清楚了，则无需添加额外的词。

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

API 资源名称

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

不要将 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 示例的版本控制

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

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

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

如果示例 YAML 位于独立文件中，请查找并查看将其作为参考的主题。验证使用独立 YAML 的任何主题是否都定义了适当的版本信息。如果没有主题引用独立 YAML 文件，请考虑将其删除而不是更新它。

例如，如果您正在编写与 Kubernetes 版本 1.8 相关的教程，则 Markdown 文件的前言应如下所示

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

在代码和配置示例中，不要包含有关替代版本的注释。请注意不要在示例中包含不正确的语句作为注释，例如

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

Kubernetes.io 词汇表

要在网站上保持一致使用的 Kubernetes 特定术语和词汇表。

短代码

Hugo 短代码 有助于创建不同的修辞诉求级别。我们的文档支持此类别中的三种不同短代码：**注意** {{< note >}}、**小心** {{< caution >}} 和**警告** {{< 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. 列表中包含嵌入式注释的第二个项目

   注意

   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 语句中的短代码将中断构建。您必须在调用 include 之前和之后将它们插入父文档中。例如

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

Markdown 元素

换行符

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

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

标题

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

段落

链接

列表

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

• 如果列表中的一个或多个项目是完整的句子，则以句号结束列表中的每个项目。为了保持一致性，通常所有项目都应该是完整的句子，或者都不应该是完整的句子。

  注意

  作为不完整介绍性句子一部分的有序列表可以使用小写字母，并且标 punctuation 就像每个项目都是介绍性句子的一部分一样。

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

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

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

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

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

表格

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

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

内容最佳实践

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

使用现在时

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

使用主动语态

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

使用简单直接的语言

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

以“您”称呼读者

避免使用拉丁语短语

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

例外情况：使用“etc.”表示“et cetera”。

应避免的模式

避免使用“我们”

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

避免使用术语和习语

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

避免做出关于未来的陈述

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

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

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

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

避免使用假设读者具备特定理解水平的词语

避免使用“只是”、“简单地”、“容易”、“轻松地”或“简单”等词语。这些词语不会增加价值。

EditorConfig 文件

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

后续步骤

• 了解如何编写新主题。
• 了解如何使用页面模板。
• 了解自定义 Hugo 短代码。
• 了解如何创建拉取请求。