Knative 文档 Word and Phrase List 详解：术语大小写、情态动词与版本号书写规范

• 文档
• 教程
• 云原生

contribute-to-docs/style-guide/word-and-phrase-list.md 是 Knative 官方文档仓库（Knative docs 项目）中的“词汇与短语清单”，以一张 Correct Term / Incorrect Term(s) / Notes 三列表格，逐条定义了 Knative 全部文档中术语、组件名、情态动词与版本号应使用和不应用的写法。本文逐条解读该清单的规则与背后理由，并结合本仓库的文档实例与 MkDocs 构建配置说明这些规范是如何被实际约束与检验的；读完后，你能写出符合 Knative 文档风格评审要求、与现有文档术语完全一致的新内容。

一、词汇清单在 Knative 文档体系中的位置

词汇清单是 Knative 风格指南（style guide）的组成部分。风格指南总览 将其与另外四篇文档并列：

• Documenting code：代码与代码片段的书写规范；
• Formatting standard and conventions：标题大小写、链接、表格等排版规范；
• Voice and language：时态、语态、称谓与用词习惯；
• Content re-use：通过docs/snippets目录复用公共内容。

贡献者指南 的 Style 小节同样把 Word and phrase list 列为提交文档前需要对照的标准之一。清单开头还给出了一条拼写基准：单词的正确拼写以 Merriam-Webster 词典为准（即拼写争议以该权威词典为最终依据）。

这条清单之所以重要，可以从本仓库的站点构建配置看出：Knative 文档站基于 Material for MkDocs 构建（见 mkdocs.yml 中site_name: Knative、theme.name: material配置），并启用了全文搜索插件 search plugin（其中separator配置使得serving.knative.dev/blibble这类路径可被拆词检索）与awesome-nav子树导航。术语在数百篇文档间保持统一拼写与大小写，是搜索命中、导航定位与跨文档一致性（例如Broker、Knative Serving在 serving 文档 与 eventing 文档 中反复出现）的基础。

二、词表速查：完整 Word and Phrase List

下表为 word-and-phrase-list.md 的完整内容（42 条规则，保留英文原貌以便直接对照）。第三列 Notes 为原文给出的理由：

下面按主题分组解读这些规则。

三、Knative 组件名与专有名词的写法

3.1 组件全名：Knative Serving / Knative Eventing / Knative Service

三条规则的共同点是：组件一律用完整正式名称，且大小写严格固定。ksvc、svc这类 kn CLI 中的资源简写不能进入文档正文；serving、eventing这类全小写缩写同样不被接受，以避免与 Kubernetes 生态中的普通词汇（如 ksvc 之于 service）混淆。在本仓库中可以看到规范的落地：serving 文档目录 通篇使用 “Knative Serving”，Kafka Broker 文档 使用 “Knative Kafka Broker” 并写 “CloudEvents”（而非 “cloud events”）。

3.2 API 对象与产品专有名词的大小写

词表中大量条目是大小写规则：Broker、Channel、Trigger、ConfigMap、CloudEvent必须大写，而event、event source、component、eventing必须小写。这与 排版规范 中 “Use upper camel case for Knative API objects” 一节互相印证：

Channels / Broker / ContainerSource 等 Knative API 对象使用 Upper Camel Case（示例中明确 Channels 对 channels、Broker 对 broker、ContainerSource 对 Container Source）。

可以推断出这条规范的内在逻辑：是 Knative 的 API 对象（Kubernetes 资源类型）就大写首字母；不是 API 对象的普通名词（event、component）一律小写。产品专有名词则遵循各自官方拼写：Docker、Kubernetes首字母大写，而minikube按 minikube 官方项目的拼写保持全小写。类似的“看似随意实则固定”的名称还有：

其中 “knative/docsGitHub repository” 一条的 Notes 特别说明：这条规则适用于每一个 Knative 仓库——引用仓库时写仓库的完整名称（组织名/仓库名），而不写 “Docs repo” 之类的口语化简称。

四、CLI 与标准输入/输出

这几条规则的共同取向是：正文散文里用全称与约定缩写，把stdin/stdout这类实现层缩写留给代码与命令上下文。这与 Knative 文档大量出现 kn CLI 操作手册类内容的定位一致——读者在文档里看到的是kn命令的用法，而文档对工具的指代统一为 “CLI”。

五、情态动词与逻辑连接词的用法

最后一条值得展开：词表把should整词列为禁用（Correct Term 栏为空，Incorrect 栏为 should）。Notes 原文是：should 语义含糊，它暗示动作被推荐但是可选的；如果作者本意是规定读者必须执行某动作，should 就是不合适的选择。这与 Voice and language 中 “简单直接、避免无价值词汇” 的要求一脉相承——指令性文档应当用祈使句直接陈述动作（例如 “Run the command.”），而不是用 should 模糊义务边界。

六、禁用方向性语言

三条 Notes 都是同一句话：“Don't use directional language to refer to a position in a document.”（不要用方向性语言指代文档中的位置）。

这条规则的理由在 Getting started 的排版指南 中也得到了呼应：该指南要求表格必须用一句话引入（例如 “The following table lists…”），即引导读者用 “following table” 而不是 “table below”。从源码结构看，Knative 文档站通过awesome-nav插件按子树自动生成导航、同一内容还会被 snippets 机制 复用插入到不同页面，页面中“上/下”的相对位置会随导航结构和复用位置变化，因此方向性指代（the table below / the section above）是不可靠的，必须用 “following / earlier / later” 这类相对锚点。

七、版本号书写规范

词表中占比最大的主题就是版本号，共 11 条规则，可归纳为三层。

7.1 版本前缀只用 v

Notes 原文：Preface version numbers with "v"。即版本数字前统一加小写v，不加句点，不用 “version” 或 “ver.” 字样。本仓库自身的命名就是例证：发布博客文章的文件名为 announcing-knative-v1-20-release.md，从announcing-knative-v0-2-release.md到announcing-knative-v1-23-release.md全部遵循 “v + 版本数字” 的格式。

7.2 范围表达：用 and/or earlier/later，不用比较词或符号

要点：描述版本区间时，用自然语言 “and/or earlier（含/不含更早）” 和 “and/or later（含/不含更晚）”，明确“边界是否包含”；禁止用 lower/higher、below/above（这又是方向性语言），也禁止用<=、>=符号——符号在自然语言段落中可读性差，且容易与 YAML、命令中的真实比较运算符混淆。

7.3 Patch 版本用三位数字，省略通配符

这两条规则保证版本号在“精度”上自洽：提到哪个粒度就写到哪个粒度，不写v1.6.X这种半通配形式；一旦讨论到 patch 级兼容性，必须写全v2.7.0这样的三位数字，避免读者把 minor 版本误当作 patch 版本。

八、如何在本地验证这些规范

风格清单最终要靠文档站的实际渲染来检验。根据 本地预览指南，修改 word-and-phrase-list.md 或任何文档后，可在仓库根目录运行 Docker 容器启动实时预览：

./hack/docker/run.sh

然后访问 http://localhost:8000 ，修改./docs下任何文件会自动热重载。也可以直接用原生 MkDocs：

pip install -r requirements.txt mkdocs serve

验证术语一致性时的两个配套检查点：

1. 表格书写本身要符合排版规范：词表是一张典型的 Markdown 表格，而 formatting 指南 要求“用一句话引入表格”、嵌套列表缩进四个空格、列表与上文之间留空行——维护词表新增条目时，应保持表格渲染不塌、Notes 列措辞风格统一；
2. 与风格指南其余部分联动检查：标题用 sentence case（示例）、过程性标题用祈使句（“Install Knative Serving” 而非 “Installation of Knative Serving”）、正文用一般现在时与主动语态（voice-and-language.md）、避免 “currently”“new” 这类会快速过期的措辞（示例）、避免 “just / simply / easy”（示例）。

以一个综合改写示例说明多条规则的叠加效果（示例文本为演示用途）：

改写前（违反多处规则）：

The new eventing component can be installed below. You may run the ksvc command in the command-line tool. For versions <= v1.20 and below, you should configure auto TLS.

改写后（逐条应用词表规则）：

You can install Knative Eventing in the following section. Run the Knative Service command in the CLI. For versions v1.20.0 or earlier, configure autoTLS.

逐条对应：删除会过期的 “new”；“eventing component” → “Knative Eventing”（组件全名）；“below” → “following”（方向性语言）；“may” → “can”（许可/可选动作）；“ksvc” → “Knative Service”；“command-line tool” → “CLI”；<=与 “and below” → “or earlier”（注意此处改为不含边界，按语义选择）；patch 级写成三位数字 “v1.20.0”；“should” 去掉、改为祈使句；“auto TLS” → “autoTLS”。

九、小结

• 该词表是 Knative 文档风格的硬性参照，共 42 条规则，完整定义在 word-and-phrase-list.md；
• 大小写规则可一句话概括：Knative API 对象（Broker、Channel、Trigger、ConfigMap、CloudEvent）与产品专有名词（Docker、Kubernetes）按固定大小写书写，普通名词（event、component、autoscaling）一律小写；
• 情态动词遵循 can（许可/可选）、might（可能性）、because（因果）的分工，may 与 should 基本禁用；
• 方向性指代（above/below）一律替换为 earlier/following/later；
• 版本号统一v前缀、and/or earlier/later 范围表达、patch 级三位数字、不写通配符；
• 规范与 Material for MkDocs 构建、搜索与导航配置共同作用，保证 Knative 文档站在数百篇文档间保持术语一致、可搜索、可维护。

• 文档
• 教程
• 云原生