大家好，今天让我们来聊聊项目技术文档。

正如我在推特上所说的，我将会在接下来的一段时间里，来分享我在过去几年里参与内部或者开源项目技术文档的时候，学到的一些有用的经验。

我绝不会说我是技术文档方面的专家，但是从个人习惯来说，我确实算是比较喜欢写文档的那类工程师。

与其说是为了说教式地描述如何写文档，不如说是兴趣使然地对这个主题的讨论。

那么言归正传，我们先来聊聊项目技术文档是什么。

从我的观察结果来说，计算机行业的项目技术文档可以分为两类：

• 手册，也就是纯粹的 Manual Book，包含了你执行 man <cmd> 或者 Swagger API 这样列表式的指南。
• 综合文档，类似于 Kafka Docs 或者 Kubernetes Docs 这样的，同时面向用户和开发者，并且更专注于教程和概念的综合文档。

本系列的博文会着重于 综合文档 这一类，这也是大家在工作上更常见、更有概率参与维护的一类文档。在接下来的篇幅中，没有特别说明的话，技术文档这个词都会指代 综合文档。

而 手册 类的文档一般来说都已经直接包含在了项目本体的代码仓库里，结构化程度也没有那么多层。

¶我所理解的技术文档

其实很难精确定义技术文档是什么，因为 CNCF, Apache, Linux Foundation 等开源机构自身的文档可以说是各有各的思路和设计哲学。

但是如果要找出技术文档在底层框架上和其他类型的文档的区别的话，还是容易的。计算机行业的技术文档，多半具备这些特点：

• 文档应由版本控制工具进行托管的，无论是 Git 还是 Mercurial。
• 文档应具备一系列根据实际需求创建的校验和开发者工具，并且配置与之对应的 CI/CD 流程。
• 文档应具备预发布/渲染机制，例如在 Merge Request 中提供新版本的 Preview 渲染。

任何开源/商业项目的开发，抽象到最后本质都是 工程学 的一个分支。

用工程学的思维进行文档代码库的设计，并且根据实际环境进行长期的迭代和跟踪，也许就是技术文档和常规文档的最大的区别。

¶版本控制

正如标题所言，今天这篇博文我们不谈技术文档的内容怎么写，而只谈工程学上，怎么给技术文档打好地基。

技术文档区别于散文、议论文乃至于学术论文，有几个独特的点：

• 对 “精确” 的要求极高。
• 迭代速度极快。热门项目的技术文档往往有五位数甚至六位数的 PR。
• 参与人数极多。公司内部项目几十上百人参与，开源热门项目往往上千人。

这些特点决定了，如果技术文档不托管在版本控制软件中，很容易在短时间里失控（内容失控 + 管理失控）。

因为不同人的行文风格差异很大，对于热门项目来说，确保行文和用词的一致性是很困难的。

所以不可避免地，需要使用 Merge Request 或者 Pull Request 这样的机制来进行文档的审核。这样，不同分支的管理者，就可以根据开发者规范和本地化风格规范，对文档的风格进行长期的跟踪和维持。

作为案例，Kubernetes 中文文档的开发者规范就做得很不错。

在 Repository 中，大家使用 script/lsync.sh 来对上游分支（也就是英语分支）进行提交的跟踪。对于单个文档页面，只要最后一次的中文同步提交早于最后一次的英语上游提交，便是做没有完成上游同步。

举个例子，当页面 Ingress 控制器的上游英语版本发生了改变以后，文档贡献者就可以非常轻易地发现更新内容，根据中文本地化样式指南的规范，修改并且提交 PR 来确保下游简中分支的同步：

$ scripts/lsync.sh content/zh-cn/docs/concepts/services-networking/ingress-controllers.mddiff --git a/content/en/docs/concepts/services-networking/ingress-controllers.md b/content/en/docs/concepts/services-networking/ingress-controllers.mdindex 7391839f85..fc19265b39 100644--- a/content/en/docs/concepts/services-networking/ingress-controllers.md+++ b/content/en/docs/concepts/services-networking/ingress-controllers.md@@ -41,6 +41,7 @@ Kubernetes as a project supports and maintains [AWS](https://github.com/kubernet * [Easegress IngressController](https://github.com/megaease/easegress/blob/main/doc/reference/ingresscontroller.md) is an [Easegress](https://megaease.com/easegress/) based API gateway that can run as an ingress controller. * F5 BIG-IP [Container Ingress Services for Kubernetes](https://clouddocs.f5.com/containers/latest/userguide/kubernetes/)   lets you use an Ingress to configure F5 BIG-IP virtual servers.+* [FortiADC Ingress Controller](https://docs.fortinet.com/document/fortiadc/7.0.0/fortiadc-ingress-controller-1-0/742835/fortiadc-ingress-controller-overview) support the Kubernetes Ingress resources and allows you to manage FortiADC objects from Kubernetes * [Gloo](https://gloo.solo.io) is an open-source...