文档风格指南

本页提供了 Kubernetes 文档的写作风格指南。这些是指南，而非规则。请自行判断，如有需要，可以通过 Pull Request 提出对本文档的修改建议。

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

风格指南的修改由 SIG Docs 小组共同完成。要提出修改或新增建议，请将其添加到即将召开的 SIG Docs 会议议程中，并参加会议参与讨论。

语言

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

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

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

文档格式标准

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

当您特指与某个 API 对象交互时，使用驼峰式大写（UpperCamelCase），也称为 Pascal Case。您可能在API 参考中看到不同的首字母大写形式，例如 "configMap"。在撰写通用文档时，最好使用驼峰式大写，例如称之为 "ConfigMap" 而不是 "configMap"。

当您泛指某个 API 对象时，使用句式大写。

以下示例重点介绍首字母大写。有关 API 对象名称格式的更多信息，请查阅代码风格中的相关指导。

对占位符使用尖括号

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

显示 Pod 信息

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

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

对用户界面元素使用粗体

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

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

引用内容内的标点使用国际标准

行内代码格式

对行内代码和命令使用代码风格

在 HTML 文档中，对行内代码使用 <code> 标签。在 Markdown 文档中，使用反引号 (`)。然而，像 StatefulSet 或 ConfigMap 这样的 API Kind 按原样书写（不使用反引号）；这允许使用所有格撇号。

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

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

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

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

对字符串和整数字段值使用常规风格

对于字符串或整数类型的字段值，使用常规风格，不带引号。

然而，如果字段值可能与 API Kind 混淆，请考虑使用引号。

引用 Kubernetes API 资源

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

关于 "resource" 的澄清

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

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

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

何时使用 Kubernetes API 术语

不同的 Kubernetes API 术语包括：

• API Kind：在 API URL 中使用的名称（例如 pods、namespaces）。API Kind 有时也称为 资源类型（resource types）。
• API Resource：API Kind 的单个实例（例如 pod、secret）。
• Object：一种充当 "意图记录" 的 resource。对象是集群特定部分的期望状态，Kubernetes 控制平面会努力维护该状态。Kubernetes API 中的所有对象也都是 resource。

为了清晰起见，在 Kubernetes 文档中引用 API resource 时，可以添加 "resource" 或 "object"。例如：写 "一个 Secret 对象" 而不是 "一个 Secret"。如果仅凭首字母大写就能清楚表达，则无需添加额外的词。

当重组句式有助于避免误解时，请考虑重述。常见的情况是您想用 API Kind（例如 “Secret”）开头一个句子；由于英语及其他语言的句子开头字母会大写，读者无法区分您是指 API Kind 还是泛指概念。重述可以提供帮助。

API 资源名称

始终使用驼峰式大写（UpperCamelCase）（也称为 PascalCase）格式化 API 资源名称。不要对 API Kind 使用代码格式。

不要将 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
...

公式和方程式

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

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

在合理的情况下，优先使用行内公式，但如果 math 块可能对读者有帮助，您也可以使用。

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

Kubernetes.io 词汇列表

一份 Kubernetes 特有术语和词汇列表，供全站一致使用。

Shortcodes

Hugo Shortcodes 有助于创建不同修辞层级。我们的文档支持此类别中的三种不同 Shortcode：注意 {{< note >}}、小心 {{< caution >}} 和警告 {{< 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 分钟，或直到凝固。

Include 语句

Include 语句内的 Shortcode 会导致构建失败。您必须将它们插入到父文档中，在调用 include 之前和之后。例如：

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

Markdown 元素

换行符

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

在 Markdown 源文件中，适当时手动换行。由于 git 工具和 GitHub 网站按行生成文件差异（diff），手动换长行有助于审查者轻松找到 PR 中所做的更改并提供反馈。这也有助于下游本地化团队，他们按行跟踪上游更改。例如，可以在句末或标点符号处换行。一个例外是 Markdown 链接或 shortcode 应该在单行中。

标题和页面标题

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

段落

链接

列表

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

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

  注意

  作为不完整引言句子一部分的有序列表可以使用小写字母开头，并按照每个项是引言句一部分的方式添加标点。

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

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

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

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

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

表格

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

• 使用Hugo shortcodes 为表格添加表标题。

内容最佳实践

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

使用现在时

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

使用主动语态

例外：如果使用主动语态会导致结构awkward（不自然），则使用被动语态。

使用简单直接的语言

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

将读者称为“你”

避免拉丁语短语

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

例外：对 et cetera 使用 "etc."。

要避免的模式

避免使用“我们”

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

避免使用行话和习语

有些读者的母语不是英语。避免使用行话和习语，以帮助他们更好地理解。

避免关于未来的陈述

避免做出承诺或给出关于未来的暗示。如果你需要谈论一个 Alpha 特性，将文本放在一个标识其为 Alpha 信息的标题下。

一个例外是关于已宣布的在未来版本中移除的弃用功能的文档。这类文档的一个例子是弃用 API 迁移指南。

避免很快会过时的陈述

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

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

避免使用“仅仅 (just)”、“简单地 (simply)”、“容易 (easy)”、“轻松地 (easily)”或“简单 (simple)”等词语。这些词语并不能增加价值。

EditorConfig 文件

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

下一步

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