文档样式指南

本页提供 Kubernetes 文档的写作风格指南。这些是指南，而不是规则。请使用您的最佳判断，并随时在拉取请求中建议更改此文档。

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

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

语言

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

在 本地化 Kubernetes 文档 中描述了为不同语言本地化文档的方式。

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

文档格式标准

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

当您专门指与 API 对象交互时，请使用 UpperCamelCase，也称为帕斯卡大小写。您可能会在 API 参考 中看到不同的大小写，例如“configMap”。在编写一般文档时，最好使用大写驼峰式命名法，将其称为“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 使用“资源”一词来指代 API 资源。例如，URL 路径 /apis/apps/v1/namespaces/default/deployments/my-app 代表 default 命名空间 中名为“my-app”的 Deployment。在 HTTP 行话中，命名空间 是一种资源 - 与所有 Web URL 标识资源的方式相同。

Kubernetes 文档还使用“资源”来谈论 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 资源时添加“资源”或“对象”。例如：写“一个 Secret 对象”而不是“一个 Secret”。如果从大写字母就可以清楚地看出，您不需要添加额外的词。

考虑在更改有助于避免误解时重新措辞。常见的情况是您想用 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. 在列表中使用注意短代码

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

包含语句

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

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

Markdown 元素

换行符

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

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

标题

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

段落

链接

列表

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

• 如果列表中有一个或多个项目是完整的句子，则在列表中的每个项目后添加句号。为了保持一致性，通常所有项目或全部都不应该是完整的句子。

  注意

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

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

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

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

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

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

表格

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

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

内容最佳实践

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

使用现在时

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

使用主动语态

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

使用简单直接的语言

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

将读者称为“您”

避免使用拉丁语短语

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

例外：使用“等”表示“等等”。

要避免的模式

避免使用“我们”

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

避免使用行话和习语

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

避免关于未来的陈述

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

此规则的例外是有关已宣布的弃用内容的文档，这些弃用内容的目标是在未来版本中删除。此类文档的一个示例是 弃用 API 迁移指南。

避免很快就会过时的陈述

避免使用“当前”和“新”等词语。今天是新功能的，可能在几个月后就不算新了。

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

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

EditorConfig 文件

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

下一步

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