文档样式指南

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

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

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

语言

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

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

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

文档格式标准

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

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

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

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

在占位符中使用尖括号

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

显示有关 Pod 的信息：

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

如果名字空间被忽略，默认为 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 文档在讨论 CPU 和内存请求以及限制也使用“资源（resource）”一词。 将 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"。 如果仅大写就能明确含义，那么无需添加额外的单词。

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

API 资源名称

始终使用大写驼峰式命名法 （也称为 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: <教程标题>
min-kubernetes-server-version: v1.8
---

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

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

Kubernetes.io 术语列表

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

短代码（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 的第二个条目

   说明：

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

3. 列表中第三个条目

4. 列表中第四个条目

小心（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 链接或短代码应位于一行中。

大标题和小标题

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

段落

链接

列表

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

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

  说明：

  编号列表如果是不完整的介绍性句子的一部分，可以全部用小写字母，并按照 每个条目都是句子的一部分来看待和处理。

• 在编号列表中，使用数字 1（1.）。

• 对非排序列表，使用加号（+）、星号（*）、或者减号（-）。

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

• 对于嵌套的列表，相对缩进四个空格（例如，⋅⋅⋅⋅）。

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

表格

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

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

内容最佳实践

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

使用现在时态

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

使用主动语态

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

使用简单直接的语言

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

将读者称为“你”

避免拉丁短语

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

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

应避免的模式

避免使用“我们”

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

避免使用俚语或行话

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

避免关于将来的陈述

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

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

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

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

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

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

编辑器配置文件

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

接下来

• 了解编写新主题。
• 了解页面内容类型。
• 了解定制 Hugo 短代码。
• 了解发起 PR。