Knative 文档程序性主题模板实战：用标准结构编写高质量的 How-to 教程-开发者社区

文档
教程
云原生

【免费下载链接】docs

User documentation for Knative components.

项目地址：https://gitcode.com/gh_mirrors/docs1/docs

本文以 Knative 官方文档仓库中的程序性主题模板（Procedure template）为核心，系统讲解 Knative 文档体系中 how-to（操作指南）类页面的标准编写方法：包括主题导语、概述、前置条件、分步任务的完整骨架，以及表格、列表、提示框、标签页等常用内容元素的排版规范。读完本文，你可以直接复用这套模板与配套风格指南，为 Knative Serving、Knative Eventing 等功能编写结构统一、便于检索、可维护的操作教程。

一、什么是程序性主题（Procedure Topic）

在 Knative 的文档体系中，Procedure（程序性主题）是一种专门面向"读者要完成某个具体目标"的内容类型。与解释"事物是什么、如何工作"的概念型主题（Concept）不同，程序性主题以详细步骤为核心，同时附带少量任务上下文，帮助读者一步步完成诸如"配置一个 Broker""部署一个 Knative Service"这样的实际操作。

仓库中新建文档指南对各类内容类型做了明确界定：Procedure 以一系列步骤写成，对功能只做最小化解释，并通过链接引导读者跳转到提供背景知识的概念页。这类页面要求包含自动化测试，以保证技术准确性。

程序性主题模板就是为这类页面准备的标准化骨架，它规定了程序性主题应包含的固定章节：主题导语（topic sentence）、概述（Overview）、前置条件（Prerequisites）、以及每一个任务（Task）的分节。

上图（位于 contribute-to-docs/images/annotated-procedure-topic.png）展示了仓库中用于注解程序性主题各组成部分的示意图，可以看到一个完整的 how-to 页面由主题导语、前置条件、步骤等区域共同构成。

二、模板的整体骨架

模板的顶层结构如下，这也是程序性主题页面最终呈现的章节顺序：

章节	作用	是否必需
主题导语（topic sentence）	用一两句话描述主题本身，帮助读者判断该页面是否适合自己	必需
Overview（概述）	用几句话介绍主题涉及的背景知识	视情况
任务清单（ordered list）	当存在多个任务且须按顺序完成时，列出全部任务并附带锚点链接	视情况
Prerequisites（前置条件）	说明开始任务前必须具备的安装、权限或环境要求	视情况
Task 1 / Task 2 ...	每个任务一节，内含分步说明	必需

主题导语（topic sentence）

模板强调导语要描述主题本身，而不是主题的研究对象。例如，写一篇关于配置 Broker 的教程时，导语应该写"This topic instructs how to set up a broker."，而不是直接去解释 Broker 是什么——后者属于 Overview 的职责。

概述与任务清单

如果主题的背景信息有用，就在 Overview 中补充几句。例如主题是关于配置 Broker 的，可以在概述中提供一些关于 Broker 的上下文。

当流程中有多个任务且必须按顺序完成时，需要在 Overview 之后用一个有序列表列出每个任务，并附上指向各任务标题的锚点链接：

To [task]: 1. [Name of Task 1 (for example, Apply default configuration)](#task-1) 1. [Optional: Name of Task 2](#task-2)

模板特别提醒：除非任务数量特别多，不要在任务标题中使用编号引导语。例如应写"Apply default configuration"，而不是"Task 1: Apply default configuration"，这样标题更简洁，也更利于搜索定位。

三、可复制的完整模板代码

模板中给出了可直接复制使用的标准 Markdown 骨架。这里完整还原，并附上必要的注释说明：

This topic describes... Write a sentence or two that describes the topic itself, not the subject of the topic. The goal of the topic sentence is to help readers understand if this topic is for them. For example, "This topic instructs how to set up a broker." ## Overview Write a few sentences to describe the subject of the topic, if useful. For example, if the topic is about configuring a broker, you might provide some useful context about brokers. If there are multiple tasks in the procedure and they must be completed in order, create an ordered list that contains each task in the topic. Use bullets for sub-tasks. Include anchor links to the headings for each task. To [task]: 1. [Name of Task 1 (for example, Apply default configuration)](#task-1) 1. [Optional: Name of Task 2](#task-2) !!! note Unless the number of tasks in the procedure is particularly high, do not use numbered lead-ins in the task headings. For example, instead of "Task 1: Apply default configuration", use "Apply default configuration". ## Prerequisites Use one of the following formats for the Prerequisites section. ### Formatting for two or more prerequisites If there are two or more prerequisites, use the following format. Include links for more information, if necessary. Before you [task], you must have/do: * Prerequisite. See [Link](). * Prerequisite. See [Link](). For example: Before you implement Apache Kafka Broker, you must have: * Knative Eventing. See Installing the Eventing component. * An Apache Kafka cluster. See Link to Instructions to Download. ### Format for one prerequisite If there is one prerequisite, use the following format. Include a link for more information, if necessary. Before you [task], you must have/do [prerequisite]. See Link. For example: Before you create the `helloworld-java` sample app, you must have a Kubernetes cluster with Knative installed and DNS configured. See the [installation instructions](https://link.gitcode.com/i/39b94c9def53e083de34fc2f4127edc4) if you need to create one. ## Task 1 Write a few sentences to describe the task and provide additional context on the task. !!! note When writing a single-step procedure, write the step in one sentence and make it a bullet. The signposting is important given readers are strongly inclined to look for numbered steps and bullet points when searching for instructions. If possible, expand the procedure to include at least one more step. Few procedures truly require a single step. [Task]: 1. Step 1 1. Step 2 ## Optional: Task 2 If the task is optional, put "Optional:" in the heading. Write a few sentences to describe the task and provide additional context on the task. [Task]: 1. Step 1 2. Step 2

注意：原模板示例中的[installation instructions](https://link.gitcode.com/i/39b94c9def53e083de34fc2f4127edc4)是相对模板文件所在位置的局部路径。在实际使用模板撰写正文时，应把这类链接转换为从仓库根目录（docs/）出发的全局相对路径，例如仓库中的 Knative 安装文档，以避免链接失效。

四、前置条件（Prerequisites）的两种写法

模板要求根据前置条件数量选择两种格式之一，且尽量附带"了解更多"的链接。

两个及以上前置条件：使用列表

格式为"Before you [task], you must have/do:"后接无序列表，每项为一条前置条件并可附链接。模板给出的示例：

Before you implement Apache Kafka Broker, you must have:

Knative Eventing. See Installing the Eventing component.
An Apache Kafka cluster. See Link to Instructions to Download.

这条规则在仓库实际文档中大量使用。例如 Knative Eventing 安装文档在要求安装组件时，就会把"一个安装了 Knative 的 Kubernetes 集群"等前置条件用列表列出。

单个前置条件：使用单句格式

格式为"Before you [task], you must have/do [prerequisite]. See Link."，全部写在一句话中。模板示例：

Before you create thehelloworld-javasample app, you must have a Kubernetes cluster with Knative installed and DNS configured.

五、任务的编写要点

普通任务：步骤使用有序列表

每个任务先用几句话描述该任务并提供上下文，然后以[Task]:引出步骤的有序列表：

[Task]: 1. Step 1 1. Step 2

单步骤任务的特殊处理

模板特别强调：写单步骤流程时，把步骤写成一个句子并用 bullet 呈现。原因是读者在查找指令时，倾向于在文档中寻找编号步骤和项目符号；如果可能，尽量把流程扩充到至少两个步骤——真正只需要一步的流程非常少。

可选任务：标题加"Optional:"前缀

如果某个任务不是必须执行的，在标题开头加上Optional:，例如## Optional: Task 2，让读者一眼识别出可以跳过。

任务标题不使用编号引导

再次强调模板中的提示：除非任务数量特别多，不要用"Task 1:"这类编号开头，直接用动词短语作标题（如"Apply default configuration"）。这一条与格式规范中"程序性标题使用祈使句（imperative）"的要求一致——标题应当直截了当地告诉读者需要执行什么动作。

六、常用内容元素与排版示例

模板的第二大部分提供了程序性主题中常见内容类型的标准写法，均可直接复制使用。

Markdown 嵌入图片

标准写法如下（路径已转换为仓库根相对路径）：

[![Annotated procedure topic](https://raw.gitcode.com/gh_mirrors/docs1/docs/raw/6b2afb10834fede5952f09f8c5154d7070c7cfe0/contribute-to-docs/images/annotated-procedure-topic.png?utm_source=gitcode_repo_files)](https://link.gitcode.com/i/36c23ec2bf5aa987c3fb2c2722284907)

表格

写表格前先用一句话引入表格，说明它列出的是什么信息。

标准 Markdown 表格模板：

|Header 1|Header 2| |--------|--------| |Data1 |Data2 | |Data3 |Data4 |

"填字段"（Fill-in-the-Fields）表格

当读者需要在一个 YAML 文件中填入大量值时，模板推荐采用"先给出 YAML 骨架，再用表格逐项说明每个字段"的组合写法：

1. Open the YAML file. ```yaml Key1: Value1 Key2: Value2 metadata: annotations: # case-sensitive Key3: Value3 Key4: Value4 Key5: Value5 spec: # Configuration specific to this broker. config: Key6: Value6 ``` 2. Change the relevant values to your needs, using the following table as a guide. | Value | Value Type | Description | |---------|----------------|--------------| | Value1 | String | Description | | Value2 | Integer | Description | | Value3 | String | Description | | Value4 | String | Description | | Value5 | Float | Description | | Value6 | String | Description |

这种"示例 YAML + 字段表"的结构在仓库实际文档中很常见。例如 Eventing 文档的 Sinks 部分在说明sink的ref、uri等字段时，就用表格列出每个字段的说明与"必需/可选"属性；Getting Started 中的 Service 部署教程则同时给出 YAML 版与kn命令版两种写法。这也印证了模板"同一流程的多个版本放入 Tabs"的约定（见下文）。

有序列表与嵌套

介绍性句子后接有序列表，可选在每项前加加粗引导语。注意：列表与前面的句子之间必须空一行，否则 Markdown 无法正确渲染。

标准格式：

Introductory sentence: 1. Item 1 1. Item 2 1. Item 3

带加粗引导语的版本：

Introductory sentence: 1. **Lead-in description:** Item 1 1. **Lead-in description:** Item 2 1. **Lead-in description:** Item 3

嵌套有序列表时，子项相对父项缩进四个空格：

Introductory sentence: 1. Item 1 1. Item 1a 1. Item 2

无序列表与嵌套

与有序列表同理，介绍句后接项目符号，缩进规则同样是子项缩进四个空格：

Introductory sentence: * List item * List sub-item * List item

Notes 与 Warnings 提示框

Knative 文档基于 Material for MkDocs 构建（见仓库 mkdocs.yml 中启用的admonition扩展），支持 admonition 提示框语法。模板中约定：

Note：提供有用但不关键的信息，正文缩进需与!!! note平齐：

!!! note This is a note.

Warning：如果提示涉及可能导致数据丢失的问题，应使用 warning 而非 note：

!!! warning This is a warning.

仓库的内容格式指南进一步补充：Knative 文档只使用 note、tip、warning 三种提示框，且要节制使用，过多的提示框会分散读者注意力。各提示框的语义为：note 提供有用但不必要的信息；tip 建议读者采取有帮助但非强制的动作；warning 提示潜在问题。

Tabs 标签页

当同一流程存在多个版本（例如knCLI 操作 vs YAML 操作）时，放在标签页（tabs）中。标签内容缩进四个空格以保证正确显示：

== "tab1 name" This is a stem: 1. This is a step. ``` This is some code. ``` 1. This is another step. == "tab2 name" This is a stem: 1. This is a step. ``` This is some code. ``` 1. This is another step.

标签页在仓库实际文档中得到了普遍应用。例如函数构建步骤和函数部署步骤都通过=== "func"与=== "kn func"两个标签分别给出func与kn func两种命令写法；部署 Knative Service 教程则用=== "kn"与=== "YAML"两个标签区分 CLI 与 YAML 两种方式。

七、配套风格规范：让程序性主题更专业

模板末尾要求代码与代码片段的格式规范参见 Style guide 中的 Documenting code 章节。除此之外，程序性主题还受整套 Knative 风格指南约束，以下几个要点与 how-to 类页面关系最密切。

标题与格式规范

格式规范中的关键规则：

标题使用 sentence case：只大写专有名词、缩写词和标题首词。如## Configure the feature（正确）而非## Configure the Feature（错误）。
标题内不使用代码格式：如## Configure the class annotation（正确）而非## Configure the \class` annotation`（错误）。
程序性标题使用祈使句：如## Install Knative Serving（正确）而非## Installation of Knative Serving。
链接一律写 Markdown 而非 HTML，内部链接必须包含.md扩展名且链接到文件而非文件夹，并注意大小写：[Kafka Broker](https://link.gitcode.com/i/39b94c9def53e083de34fc2f4127edc4)。
术语表优先用表格呈现，而不是定义列表格式。
Knative API 对象用大写驼峰：如Channel、Broker、ContainerSource。

语气与语言规范

语气与语言指南要求：

使用现在时：如"This command starts a proxy."而非"This command will start a proxy."
使用主动语态：如"You can explore the API using a browser."而非"The API can be explored using a browser."
以"you"称呼读者：如"You can create a Deployment by ..."而非"We can create a Deployment by ..."
语言简洁直接：避免"please"等多余词汇，避免俚语和拉丁语（如用"For example"而非"e.g."）。
避免承诺未来功能、避免使用"currently""new"这类很快过时的表述。

命令的文档化

Documenting code 规定命令的标准表述为"X the Y by running the command:"，先说明命令做什么，再给出命令块：

Create the service by running the command: ```bash kn create service <service-name>

Where<service-name>is the name of your Knative Service.

- 命令块语言统一使用 ```bash；CLI 输出则使用自定义样式 `{ .bash .no-copy }` 以隐藏"复制到剪贴板"按钮。 - 变量在代码块中以 `<variable-name>` 形式书写，全部小写、单词间用连字符，并在代码块下方以"Where ..."格式逐条解释；多个变量时用列表分行解释。 - 命令 flag 一律使用短格式：用 `-n` 而非 `--namespace`。 ### YAML 的文档化 文档化 YAML 时使用**两步法**：第一步创建 YAML 文件，第二步应用该文件： - 对用户创建的文件/对象，用 `kubectl apply`（它对 create 和 update 都适用，且以本地文件为事实来源）。 - 对 Knative 软件自带、随发布提供的文件（如 Knative Serving 和 Knative Eventing 的 ConfigMap），用 `kubectl edit`。 - 文档化 YAML 片段而非完整文件时，用 `...` 明确标示省略的上下文。 ### 内容复用（snippets） 仓库用 [内容复用指南](https://link.gitcode.com/i/18c410c1830f9ae15658e7e8431af779) 减少重复劳动：常用的步骤文本放在 [docs/snippets](https://link.gitcode.com/i/1257290a186fb74c3f6104846584dc19) 目录，通过 MkDocs 的 snippets 机制按需嵌入多个页面。比如 [函数构建步骤](https://link.gitcode.com/i/35ca4680867b03f824f799b02d87d117)、[函数运行步骤](https://link.gitcode.com/i/2d07ed2562b5a947ad57d7e97d3f9505) 这些片段就被 `versioned/getting-started/` 与 `versioned/functions/` 下的多个主题复用，保证了"一处修改、处处生效"。这给程序性主题编写者的启示是：**通用的过程步骤应尽量沉淀为 snippet 而非在多个页面里复制粘贴**。 ## 八、与其他内容模板的分工 程序性模板是 Knative 文档四类内容模板之一，[模板目录](https://link.gitcode.com/i/78818ba375a50906c883bed096f1f02d) 收录了全部四类： | 模板 | 适用内容 | 核心特征 | |------|----------|----------| | [Concept template](https://link.gitcode.com/i/e416e53a79408424c93aa027369f4e10) | 解释"事物是什么、如何工作" | 提供背景上下文，不含操作步骤 | | [Procedure template](https://link.gitcode.com/i/d9434d7cd744af6c304fe9379e64b648) | how-to 操作指南 | 以详细步骤为核心，附少量上下文 | | [Troubleshooting template](https://link.gitcode.com/i/5eca5aa9637b5e90143eb0796c4b2b2b) | 常见错误的排查指南 | 每条错误包含 Error Description、Symptom、Cause、Solution | | [Blog template](https://link.gitcode.com/i/4eba64d06fd3aad2123f3dd7dfc13939) | 博客文章 | 偏向个人经验叙述，发布后不维护技术准确性 | [新建文档指南](https://link.gitcode.com/i/73d0b8a78c06b0b0d35de1220efd0955) 建议的流程是：先明确读者与内容用途，再选择内容类型，然后选用对应模板，接着选择标题与文件名，参考 [风格指南](https://link.gitcode.com/i/39b94c9def53e083de34fc2f4127edc4) 写作，最后提交 PR 进入评审。 ## 九、从模板到成品：编写一个程序性主题的工作流 综合模板与配套规范，编写一个程序性主题可以归纳为以下步骤： 1. **确定主题导语**：用一两句话描述主题本身（而非研究对象），让读者判断该页是否适合自己。 2. **撰写 Overview**：提供必要的背景上下文；若流程含多个按序执行的任务，用带锚点链接的有序列表列出全部任务。 3. **列出前置条件**：根据数量选用列表格式或单句格式，并附上指向相关文档的链接（链接使用从仓库根出发的相对路径，如 [安装文档](https://link.gitcode.com/i/39b94c9def53e083de34fc2f4127edc4)）。 4. **分节编写每个任务**：用祈使句动词短语作标题，标题中不加编号引导语；可选任务加 `Optional:` 前缀；步骤使用有序列表，子步骤缩进四个空格；单步骤流程用 bullet 并尽量扩充。 5. **按需选用内容元素**：表格（含填字段表格）、代码块、提示框（note/tip/warning）、标签页（多版本流程）等，均按模板与 [格式指南](https://link.gitcode.com/i/eea351bfa075d08d90c4c344ac936e44) 的规范排版。 6. **对齐风格指南**：遵循 [格式规范](https://link.gitcode.com/i/b0d9de15c55dc96e59a1f23690f1a722) 与 [语气语言指南](https://link.gitcode.com/i/486039ed2f4a72c81634d1c0e2856b9f)，命令与 YAML 按 [Documenting code](https://link.gitcode.com/i/ec94638a258eb755deae99fd32cf60db) 的要求书写。 7. **考虑内容复用**：通用步骤优先沉淀到 [docs/snippets](https://link.gitcode.com/i/1257290a186fb74c3f6104846584dc19) 目录供多页复用。 8. **本地预览与提交**：可参考 [本地预览指南](https://link.gitcode.com/i/0cde33e076226915a4b2db1dc05fdbae) 用 `mkdocs serve` 在本地检查渲染效果，确认列表缩进、提示框、标签页等元素显示正常后提交 PR。 遵循这套模板与规范，你可以为 Knative 的各种功能写出结构统一、步骤清晰、便于搜索和引用的高质量操作教程——这也正是 Knative 官方文档保持整体一致性与可维护性的基础。