大家好，时隔两个月，我又来了。

时隔这么久一方面是最近事情比较多，已经到了并行处理的极限；一方面也是因为，文档标准总归是一个比较枯燥的话题，所以拖到了现在。

那么话不多说，我们书接上文 写好项目技术文档 - CH01. Repository 设计，接着聊聊怎么设计文档的标准和规范。

¶为什么要有标准?

在日常中，其实很少有人喜欢写文档；而愿意写文档的朋友，经常也会忽视如何设计文档的标准这一话题。毕竟能够愿意去持续地为公司内部项目贡献文档，已经弥足珍贵，有得是玩命糊屎山不写文档的人（当然，代码如文档是最好的状态；但是 99% 的从业者无法达到 Linux Kernel Docs 所描述的理想的状态）。

不过我倒是觉得，文档这东西是有传染性的。当你能够以一个比较高的标准去持续输出文档的时候，身边的其他人多多少少也会被你感染，潜移默化地体会到一个有规范的文档所带来的好处。

这里一个比较常见的案例就是，一个工作上的伙伴来问你一个曾经遇到过的 TroubleShooting，而你直接把相关的文档链接/复盘案例直接在 Thread 里甩给了他。原本需要冗长的 DM 或者 Thread 讨论的问题，直接被终结了。可以说，这是与人合作的过程中最爽的事情之一。

另一个场景是，组里来了一个萌新，他正在进行 Onboarding。这个时候他来向你询问一个内部工具的用法，而你粗暴地甩给了他一份事无巨细、Step-by-step、我奶奶来了都能跟着操作的文档的时候，你的潜意识会清晰的告诉你，这些文档为自己和萌新节省了无可计量的时间，这亦是另一种爽快。

如果说文档的有无带来的爽感是第一层级的话，那么文档的标准和规范，就是到达第二层级的爽感的必经之路。

当一个文档逐渐壮大，或者整个团队的文档意识开始提升之后，一定会遇到一个问题：文档的协作

不像代码，无论项目使用什么语言、版本管理工具、开发框架，总归有一系列非常成熟的开发规范和工具链可以使用。这意味着：

• 作为下限，项目的 OWNER 可以通过一个很低的代价，确保项目代码的基本一致性。
• 作为上限，通过 Reviewer 的严苛程度以及单元测试的高覆盖，可以让所有贡献者保持高度一致的提交风格。

而文档的协作，却更加复杂：

• 贡献者的行文风格都大相径庭。
• 不同语言的遣词造句规范，有很大的差异。
• 对于长期项目，甚至会被语言本身的变迁所困扰。
• 同义词和近义词混杂问题。

因此，文档的标准和规范的目的，就是希望在可控的范围内，尽可能地减少这些问题的出现。让多人协作的大型文档，变得更加工业化，从而实现一套囊括了文档新增和更新（以及本地化）的流水线工程，并且和上一篇 写好项目技术文档 - CH01. Repository 设计 中的文档 Repository 设计相结合，充分利用版本控制工具的优势，结合现代的 CI/CD 流水线，实现一个可跟踪、可维护、行文统一、用词标准无歧义的文档贡献系统。

¶文档标准，分哪些部分呢?

这个分类，我更多其实是参考了 Kubernetes 官方文档以及 Jenkins 官方文档的一些内容以后，自己琢磨的。

简单来说我觉得可以分为这么四块：

• Reference & Concepts —— 名词与概念参考表。
• Style Conventions —— 行文/i18N 风格指南。
• Sync Check —— 适用于多语言的 commit 同步检查。
• Ownership —— 文档/文档分支的所有权管理。

传统意义上的文档规范，其实主要指的就是 References 和 Style Conventions。前者是对整个文档中出现的专业术语和概念的标准解释，从而其他贡献者撰写的时候可以用类似于 {{\}} 这样的形式进行快捷引用。

后者是对整个文档的行文风格，遣词造句的规范。举个例子，在 Kubernetes 官方中文文档中，明确描述了，不允许在翻译中使用 “您” 作为读者的指代。这就是一个很明确的行文风格的规范。

¶当我们说标准化的时候，到底说的是什么

相信多数的读者在阅读各种开源/商用工具的文档的时候，多少遇到过一个问题：

在不同的页面中，同一个概念或者术语，居然有不同的描述

这并不是一个罕见的问题。无论是 Kubernetes，Splunk，Jenkins 这类超级项目的文档，还是说遍布 GitHub 的各种小型开源项目的文档，都会遇到这样的问题。

举个很直接的例子，在 Kubernetes 中 control-plane 是一个非常基础的概念。然而即便是如此基础的概念，在所有中文翻译版本的页面中，其实有 控制面 和 控制平面 两种翻译方法。从提交记录来看，这显然是一个因为早期批量翻译提交和行文风格规范没有完善所导致的问题。

因此这里也引申出了小节标题。当我们说标准化的时候，到底说的是什么？

我认为在这个场景里，标准化代表的就是精确、达意、全局统一的术语词典表。这个表应当包含了当前这个项目/软件所有的专业术语和概念。如果有余力，甚至应该对这个术语词典表中的每一项，进行完整的描述和概念边界的限制。

Reference & Concepts，也就是这个术语词典表，我认为是文档规范中一切的基础，是大楼的根基，是巨树的树根。

有了这个形而上的认识，下一个问题就是，如何把 Reference & Concepts 动手做起来。其实很多时候大家都会觉得把一个 PPT 或者概念上很好的东西落地到实际的 Repository 里，很困难。但是很多时候我觉得我们是被自己束缚住了。

我很喜欢一位厨子（高寒）的说法：“按照我说的做，不要按照我做的做。”

事实上在项目文档里推进标准化也是一个道理。不要在一开始想着就和 Kubernetes 文档一样，设计一个非常成熟而夸张的目录树，用来承载多如繁星的各种概念和术语。这没有必要，因为你根本做不到，并且你的所有热情会在这个过程中燃烧殆尽：

很多时候，作为一个好的开始，一张 MarkDown 写的术语表或个 CSV 文件可能就完全够用了。你完全可以写一个检查工具，放在 CI/CD 管道中用来对文档的术语进行初步的检查。这样的工具只要稍微利用正则就很容易制作。

...namespace, 命名空间control-pane, 控制平面ingress, 入口...

文档和业务代码最大的不同是，文档更像是一种活的东西，一种随着贡献者的来来去去自由生长的东西。Reference & Concepts 作为保证其符合要求生长的最底层的规则，很多时候最大的意义在于其存在本身。

¶如何让无数人，按一个风格说话

说实话，这个副标题让人绝望。

莫说让无数人按照同样的行文标准来说话；哪怕让我这个月和上个月用完全一样风格的说话，恐怕都不太容易。

所以这里就产生了一个问题，语言、或者说文章的标准化生产方法是什么。对了，就是车轱辘话。不管什么人说出来的车轱辘话，基本味道都是差不太多的。那么怎么说车轱辘话呢？

答案就是堆砌简单陈述句。

- A 是 B...