文档样式指南

本页讨论 Kubernetes 文档的样式指南。 这些仅仅是指南而不是规则。 你可以自行决定,且欢迎使用 PR 来为此文档提供修改意见。

关于为 Kubernetes 文档贡献新内容的更多信息, 可以参考文档内容指南

样式指南的变更是 SIG Docs 团队集体决定。 如要提议更改或新增条目,请先将其添加到下一次 SIG Docs 例会的议程表上,并按时参加会议讨论。

语言

Kubernetes 文档已经被翻译为多个语种 (参见 本地化 README)。

本地化 Kubernetes 文档描述了如何为一种新的语言提供本地化文档。

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

文档格式标准

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

当你与指定的 API 对象进行交互时, 使用大写驼峰式命名法, 也被称为帕斯卡拼写法(PascalCase)。 你可以在 API 参考中看到不同的大小写形式,例如 "configMap"。 在编写通用文档时,最好使用大写驼峰形式,将之称作 "ConfigMap"。

通常在讨论 API 对象时,使用 句子式大写

下面的例子关注的是大小写问题。关于如何格式化 API 对象名称的更多信息, 可参考相关的代码风格指南。

使用 Pascal 风格大小写来给出 API 对象的约定
可以 不可以
该 HorizontalPodAutoscaler 负责... 该 Horizontal pod autoscaler 负责...
每个 PodList 是一个 Pod 组成的列表。 每个 Pod List 是一个由 Pod 组成的列表。
该 Volume 对象包含一个 hostPath 字段。 此卷对象包含一个 hostPath 字段。
每个 ConfigMap 对象都是某个名字空间的一部分。 每个 configMap 对象是某个名字空间的一部分。
要管理机密数据,可以考虑使用 Secret API。 要管理机密数据,可以考虑使用秘密 API。

在占位符中使用尖括号

用尖括号表示占位符,让读者知道占位符表示的是什么。例如:

显示有关 Pod 的信息:

kubectl describe pod <Pod 名称> -n <名字空间>

如果名字空间被忽略,默认为 default,你可以省略 '-n' 参数。

用粗体字表现用户界面元素

以粗体表示用户界面元素
可以 不可以
点击 Fork 点击 "Fork"。
选择 Other 选择 "Other"。

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

新术语约定
可以 不可以
每个 集群 是一组节点 ... 每个“集群”是一组节点 ...
这些组件构成了 控制面 这些组件构成了 控制面

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

文件名、目录和路径约定
可以 不可以
打开 envars.yaml 文件 打开 envars.yaml 文件
进入到 /docs/tutorials 目录 进入到 /docs/tutorials 目录
打开 /_data/concepts.yaml 文件 打开 /_data/concepts.yaml 文件

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

标点符号约定
可以 不可以
事件记录中都包含对应的“stage”。 事件记录中都包含对应的“stage。”
此副本称作一个“fork”。 此副本称作一个“fork。”

行间代码格式

为行间代码、命令使用代码样式

对于 HTML 文档中的行间代码,使用 <code> 标记。在 Markdown 文档中,使用反引号(`)。 然而,StatefulSet 或 ConfigMap 这些 API 类别是直接书写的(不用反引号);这样允许使用表示所有格的撇号。

行间代码、命令和 API 对象约定
可以 不可以
kubectl run 命令会创建一个 Pod。 "kubectl run" 命令会创建一个 Pod。
每个节点上的 kubelet 都会获得一个 Lease… 每个节点上的 kubelet 都会获得一个 Lease
一个 PersistentVolume 代表持久存储… 一个 PersistentVolume 代表持久存储…
CustomResourceDefinition 的 .spec.group 字段… CustomResourceDefinition.spec.group 字段…
在声明式管理中,使用 kubectl apply 在声明式管理中,使用 "kubectl apply"。
用三个反引号来(```)标示代码示例 用其他语法来标示代码示例。
使用单个反引号来标示行间代码。例如:var example = true 使用两个星号(**)或者一个下划线(_)来标示行间代码。例如:var example = true
在多行代码块之前和之后使用三个反引号标示隔离的代码块。 使用多行代码块来创建示意图、流程图或者其他表示。
使用符合上下文的有意义的变量名。 使用诸如 'foo'、'bar' 和 'baz' 这类无意义且无语境的变量名。
删除代码中行尾空白。 在代码中包含行尾空白,因为屏幕抓取工具通常也会抓取空白字符。

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

对象字段名约定
可以 不可以
在配置文件中设置 replicas 字段的值。 在配置文件中设置 "replicas" 字段的值。
exec 字段的值是一个 ExecAction 对象。 "exec" 字段的值是一个 ExecAction 对象。
kube-system 名字空间中以 DaemonSet 形式运行此进程。 在 kube-system 名字空间中以 DaemonSet 形式运行此进程。

用代码样式书写 Kubernetes 命令工具和组件名

Kubernetes 命令工具和组件名
可以 不可以
kubelet 维持节点稳定性。 kubelet 负责维护节点稳定性。
kubectl 处理 API 服务器的定位和身份认证。 kubectl 处理 API 服务器的定位和身份认证。
使用该证书运行进程 kube-apiserver --client-ca-file=FILENAME 使用证书运行进程 kube-apiserver --client-ca-file=FILENAME。

用工具或组件名称开始一句话

工具或组件名称使用约定
可以 不可以
The kubeadm tool bootstraps and provisions machines in a cluster. kubeadm tool bootstraps and provisions machines in a cluster.
The kube-scheduler is the default scheduler for Kubernetes. kube-scheduler is the default scheduler for Kubernetes.

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

组件名称与通用描述
可以 不可以
Kubernetes API 服务器提供 OpenAPI 规范。 apiserver 提供 OpenAPI 规范。
聚合 API 是下级 API 服务器。 聚合 API 是下级 APIServer。

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

对于字符串或整数,使用正常样式,不要带引号。

字符串和整数字段值约定
可以 不可以
imagePullPolicy 设置为 Always。 imagePullPolicy 设置为 "Always"。
image 设置为 nginx:1.16。 image 设置为 nginx:1.16
replicas 字段值设置为 2。 replicas 字段值设置为 2

然而,在读者可能会将某些值与 API 类别混淆时,请考虑为这些值添加引号。

引用 Kubernetes API 资源

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

有关 “资源” 的阐述

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

Kubernetes 文档在讨论 CPU 和内存请求以及限制也使用“资源(resource)”一词。 将 API 资源称为 "API 资源" 往往是一个好的做法;这有助于避免与 CPU 和内存资源或其他类别的资源混淆。

如果你使用资源名称的小写复数形式,例如 deploymentsconfigmaps, 请提供额外的书面上下文来帮助读者理解你的用意。 如果你使用术语时所处的上下文中使用驼峰编码(UpperCamelCase)的名称也可行,且术语存在歧义的风险, 应该考虑使用 UpperCamelCase 形式的 API 类别。

何时使用 Kubernetes API 术语

不同 Kubernetes API 术语的说明如下:

  • API 类别 :API URL 中使用的名称(如 podsnamespaces)。 API 类别有时也称为 资源类型
  • API 资源 :API 类别的单个实例(如 podsecret
  • 对象 :作为 “意向记录” 的资源。对象是集群特定部分的期望状态, 该状态由 Kubernetes 控制平面负责维护。 Kubernetes API 中的所有对象也都是资源。

为了清晰起见,在 Kubernetes 文档中引用 API 资源时可以使用 "资源" 或 "对象"。 例如:写成 "Secret 对象" 而不是 "Secret"。 如果仅大写就能明确含义,那么无需添加额外的单词。

当修改有助于避免误解时,那就考虑修改表述。 一个常见的情况是当你想要某个句子以 "Secret" 这种 API 类别开头时; 因为英语和其他几种语言会对句首的第一个字母大写,所以读者无法确定你说的是 API 类别还是一般概念。 此时重新构词有助于让句子更清晰。

API 资源名称

始终使用大写驼峰式命名法 (也称为 PascalCase)来表达 API 资源名称。不要使用代码格式书写 API 类别。

不要将 API 对象的名称切分成多个单词。 例如请使用 PodTemplateList 而非 Pod Template List。

有关 PascalCase 和代码格式的更多信息, 请查看对 API 对象使用大写驼峰式命名法针对内嵌代码、命令与 API 对象使用代码样式

有关 Kubernetes API 术语的更多信息, 请查看 Kubernetes API 术语的相关指南。

代码段格式

不要包含命令行提示符

命令行提示符约定
可以 不可以
kubectl get pods $ kubectl get pods

将命令和输出分开

例如:

验证 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: <教程标题>
min-kubernetes-server-version: v1.8
---

在代码和配置示例中,不要包含其他版本的注释信息。 尤其要小心不要在示例中包含不正确的注释信息,例如:

apiVersion: v1 # 早期版本使用...
kind: Pod
...

Kubernetes.io 术语列表

以下特定于 Kubernetes 的术语和词汇在使用时要保持一致性。

Kubernetes.io 词汇表
术语 用法
Kubernetes Kubernetes 的首字母要保持大写。
Docker Docker 的首字母要保持大写。
SIG Docs SIG Docs 是正确拼写形式,不要用 SIG-DOCS 或其他变体。
On-premises On-premises 或 On-prem 而不是 On-premise 或其他变体。
cloud native Cloud native 或 cloud native 适合句子结构,而不是 cloud-native 或 Cloud Native。
open source Open source 或 open source 适合句子结构,而不是 open-source 或 Open Source。

短代码(Shortcodes)

Hugo 短代码(Shortcodes) 有助于创建比较漂亮的展示效果。我们的文档支持三个不同的这类短代码。 注意 {{< note >}}小心 {{< caution >}}警告 {{< warning >}}

  1. 将要突出显示的文字用短代码的开始和结束形式包围。

  2. 使用下面的语法来应用某种样式:

    {{< note >}}
    不需要前缀;短代码会自动添加前缀(注意:、小心:等)
    {{< /note >}}
    

    输出的样子是:

注释(Note)

使用短代码 {{< note >}} 来突出显示某种提示或者有助于读者的信息。

例如:

{{< note >}}
在这类短代码中仍然 _可以_ 使用 Markdown 语法。
{{< /note >}}

输出为:

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

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

1. 带嵌套 note 的第二个条目

   {{< note >}}
   警告、小心和注意短代码可以嵌套在列表中,但是要缩进四个空格。
   参见[常见短代码问题](#common-shortcode-issues)。
   {{< /note >}}

1. 列表中第三个条目

1. 列表中第四个条目

其输出为:

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

  2. 带嵌套 note 的第二个条目

  1. 列表中第三个条目

  2. 列表中第四个条目

小心(Caution)

使用 {{< caution >}} 短代码来引起读者对某段信息的重视,以避免遇到问题。

例如:

{{< caution >}}
此短代码样式仅对标记之上的一行起作用。
{{< /caution >}}

其输出为:

警告(Warning)

使用 {{< warning >}} 来表明危险或者必须要重视的一则信息。

例如:

{{< warning >}}
注意事项
{{< /warning >}}

其输出为:

常见的短代码问题

编号列表

短代码会打乱编号列表的编号,除非你在信息和标志之前都缩进四个空格。

例如:

1. 预热到 350˚F
1. 准备好面糊,倒入烘烤盘
    {{< note >}}给盘子抹上油可以达到最佳效果。{{< /note >}}
1. 烘烤 20 到 25 分钟,或者直到满意为止。

其输出结果为:

  1. 预热到 350˚F
  2. 准备好面糊,倒入烘烤盘
  3. 烘烤 20 到 25 分钟,或者直到满意为止。

Include 语句

如果短代码出现在 include 语境中,会导致网站无法构建。 你必须将他们插入到上级文档中,分别将开始标记和结束标记插入到 include 语句之前和之后。 例如:

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

Markdown 元素

换行

使用单一换行符来隔离块级内容,例如标题、列表、图片、代码块以及其他元素。 这里的例外是二级标题,必须有两个换行符。 二级标题紧随一级标题(或标题),中间没有段落或文字。

两行的留白有助于在代码编辑器中查看整个内容的结构组织。

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

大标题和小标题

访问文档的读者可能会使用屏幕抓取程序或者其他辅助技术。 屏幕抓取器是一种线性输出设备, 它们每次输出页面上的一个条目。 如果页面上内容过多,你可以使用标题来为页面组织结构。 页面的良好结构对所有读者都有帮助,使得他们更容易浏览或者过滤感兴趣的内容。

标题约定
可以 不可以
更新页面或博客在前言部分中的标题。 使用一级标题。因为 Hugo 会自动将页面前言部分的标题转化为一级标题。
使用编号的标题以便内容组织有一个更有意义的结构。 使用四级到六级标题,除非非常有必要这样。如果你要编写的内容有非常多细节,可以尝试拆分成多个不同页面。
在非博客内容页面中使用井号(# 使用下划线 ---=== 来标记一级标题。
页面正文中的小标题采用正常语句的大小写。例如:Extend kubectl with plugins 页面正文中的小标题采用首字母大写的大标题式样。例如:Extend Kubectl With Plugins
头部的页面标题采用大标题的式样。例如:title: Kubernetes API Server Bypass Risks 头部的页面标题采用正常语句的大小写。例如不要使用 title: Kubernetes API server bypass risks

段落

段落约定
可以 不可以
尝试不要让段落超出 6 句话。 用空格来缩进第一段。例如,段落前面的三个空格⋅⋅⋅会将段落缩进。
使用三个连字符(---)来创建水平线。使用水平线来分隔段落内容。例如,在故事中切换场景或者在上下文中切换主题。 使用水平线来装饰页面。
链接约定
可以 不可以
插入超级链接时给出它们所链接到的目标内容的上下文。例如:你的机器上某些端口处于开放状态。参见检查所需端口了解更详细信息。 使用“点击这里”等模糊的词语。例如:你的机器上某些端口处于打开状态。参见这里了解详细信息。
编写 Markdown 风格的链接:[链接文本](URL)。例如:[Hugo 短代码](/zh-cn/docs/contribute/style/hugo-shortcodes/#table-captions),输出是 Hugo 短代码 编写 HTML 风格的超级链接:<a href="/media/examples/link-element-example.css" target="_blank">访问我们的教程!</a>,或者创建会打开新 Tab 页签或新窗口的链接。例如:[网站示例](https://example.com){target="_blank"}

列表

将一组相互关联的内容组织到一个列表中,以便表达这些条目彼此之间有先后顺序或者某种相互关联关系。 当屏幕抓取器遇到列表时,无论该列表是否有序,它会告知用户存在一组枚举的条目。 用户可以使用箭头键来上下移动,浏览列表中条目。 网站导航链接也可以标记成列表条目,因为说到底他们也是一组相互关联的链接而已。

  • 如果列表中一个或者多个条目是完整的句子,则在每个条目末尾添加句号。 出于一致性考虑,一般要么所有条目要么没有条目是完整句子。

  • 在编号列表中,使用数字 1(1.)。

  • 对非排序列表,使用加号(+)、星号(*)、或者减号(-)。

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

  • 对于嵌套的列表,相对缩进四个空格(例如,⋅⋅⋅⋅)。

  • 列表条目可能包含多个段落。每个后续段落都要缩进或者四个空格或者一个制表符。

表格

数据表格的语义用途是呈现表格化的数据。 用户可以快速浏览表格,但屏幕抓取器需要逐行地处理数据。 表格标题可以用来给数据表提供一个描述性的标题。 辅助技术使用 HTML 表格标题元素来在页面结构中辨识表格内容。

内容最佳实践

本节包含一些建议的最佳实践,用来开发清晰、明确一致的文档内容。

使用现在时态

使用现在时态
可以 不可以
此命令启动代理。 此命令将启动一个代理。

例外:如果需要使用过去时或将来时来表达正确含义时,是可以使用的。

使用主动语态

使用主动语态
可以 不可以
你可以使用浏览器来浏览 API。 API 可以被使用浏览器来浏览。
YAML 文件给出副本个数。 副本个数是在 YAML 文件中给出的。

例外:如果主动语态会导致句子很难构造时,可以使用被动语态。

使用简单直接的语言

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

使用简单直接语言
可以 不可以
要创建 ReplicaSet,... 如果你想要创建 ReplicaSet,...
参看配置文件。 请自行查看配置文件。
查看 Pod。 使用下面的命令,我们将会看到 Pod。

将读者称为“你”

将读者称为“你”
可以 不可以
你可以通过 ... 创建一个 Deployment。 通过...我们将创建一个 Deployment。
在前面的输出中,你可以看到... 在前面的输出中,我们可以看到...

避免拉丁短语

尽可能使用英语而不是拉丁语缩写。

避免拉丁语短语
可以 不可以
例如,... e.g., ...
也就是说,... i.e., ...

例外:使用 etc. 表示等等。

应避免的模式

避免使用“我们”

在句子中使用“我们”会让人感到困惑,因为读者可能不知道这里的“我们”指的是谁。

要避免的模式
可以 不可以
版本 1.4 包含了 ... 在 1.4 版本中,我们添加了 ...
Kubernetes 为 ... 提供了一项新功能。 我们提供了一项新功能...
本页面教你如何使用 Pod。 在本页中,我们将会学到如何使用 Pod。

避免使用俚语或行话

对某些读者而言,英语是其外语。 避免使用一些俚语或行话有助于他们更方便的理解内容。

避免使用俚语或行话
可以 不可以
Internally, ... Under the hood, ...
Create a new cluster. Turn up a new cluster.

避免关于将来的陈述

要避免对将来作出承诺或暗示。如果你需要讨论的是 Alpha 功能特性, 可以将相关文字放在一个单独的标题下,标识为 Alpha 版本信息。

此规则的一个例外是对未来版本中计划移除的已废弃功能选项的文档。 此类文档的例子之一是已弃用 API 迁移指南

避免使用很快就会过时的表达

避免使用一些很快就会过时的陈述,例如“目前”、“新的”。 今天而言是新的功能,过了几个月之后就不再是新的了。

避免使用很快过时的表达
可以 不可以
在版本 1.4 中,... 在当前版本中,...
联邦功能特性提供 ... 新的联邦功能特性提供 ...

避免使用隐含用户对某技术有一定理解的词汇

避免使用“只是”、“仅仅”、“简单”、“很容易地”、“很简单”这类词汇。 这些词并没有提升文档的价值。

避免无意义词汇的注意事项
可以 不可以
在 ... 中包含一个命令 只需要在... 中包含一个命令
运行容器 ... 只需运行该容器...
你可以移除... 你可以很容易地移除...
这些步骤... 这些简单的步骤...

编辑器配置文件

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

接下来