Doc as Code (2): 从软件工具链到文档工具链

 Doc as Code是像写代码一样写文档，总体思路是使用代码的工具来编辑、管理和发布文档。这篇文章我们就来聊一聊这些工具。

世界上有很多种类型的软件，比如嵌入式软件、桌面应用程序、SaaS软件、基于Web的应用程序、手机app等。开发语言也很多，比如C/C++、Java、Python、Go、Scala、JavaScript等等。

不管哪种类型的软件，也不管是哪一种开发语言，软件开发过程中用到的工具都包括这几样：

• 管理：用来管理代码的工具

• 创作：用来编写代码的工具

  又称为集成开发环境，软件工程师大部分时间都是在这里边创作。

• 发布：用来编译、打包代码的工具

  软件工程师编写好的代码称为源代码，需要将源代码进行转换才能让计算机、手机执行。这个过程叫做编译。

• 消费：用来让用户使用软件的工具

- 1 -

管理

在引入代码管理工具之前，软件工程师使用文件系统提供的功能来管理管理代码文件。大家是这样工作的：

• 文件按照分类放在不同的目录里，使用编辑器打开文档进行编辑。

• 如果需要其他人编辑或者审核，则通过U盘、FTP、网盘、邮件等方法将文件拷贝到其他人电脑上进行操作。

• 如果改版，则新创建一个目录并将文件拷贝一份。

很多使用MS Word写文档的TW也使用同样的方法，有相同的经历。这种方法有这几个问题：

首先，多份文件拷贝占用很多磁盘空间。

其次，多份文件拷贝有时候不知道哪一份是最新的。

再次，难以在成员之间协作，需要在不同电脑之间来回拷贝文件。如果有多人修改了文件，不同人更改后的内容难以合并。

最后，这种方法存在文件丢失的可能。万一电脑硬盘损坏或者电脑丢失，可能造成不可挽回的损失。

很多年前人们就设计了软件来解决上边这些问题，这个软件叫做版本控制系统。

近几年，用得比较多的版本控制系统是SVN和Git，尤其是Git用得最多。 

（1） 管理版本

版本控制系统管理所有文件的所有版本，跟踪每个文件的变化。如果做了什么更改，觉得不合适可以随时退回到修改前的状态。

系统提供了打标记（Tag）的功能，就像时间戳一样，记录历史上某一时刻文件的内容，一般在发布版本的时候使用。在内容管理系统中这个机制叫做基线（Baseline），有相同的功能。 

系统可以比较一个文件的任意两个版本来查看有什么不同，比较的结果在Git图形界面展示如下：

红色和减号表示删除的行，绿色和加号表示增加的行。

为什么要使用纯文本文件来写文件呢，这是因为：

1. 纯文本文件才好比较

   版本管理系统已经提供了比较纯文本文件的功能。

   对于MS Word文件、图形文件的不同版本的比较，则不容易，没有现成的方案。

2. 纯文本文件更改以后，版本控制系统只需要保存变更部分内容。

   MS Word格式文件也能放到版本管理系统中，但不能实现只保存更改的部分，每个小版本都要将文件完全拷贝一份。与保存变更部分相比，这种情况占用的存储空间要大得多。

（2）权限管理

Git有一个概念叫做仓库（Repository），就像我们电脑上的C盘、D盘一样。管理员可以设置谁可以访问仓库，谁不能访问。同时可以设置谁可以修改文件，谁只能读文件。 

（3）协作

有了版本控制系统，团队成员之间的协作变得容易。

使用过内容管理系统的人一定记得在编辑某文件之前需要先检出（check-out）文件进行锁定并修改，修改完后再检入（Check-in）。这期间，其他人是不能修改这个文件的。 

使用版本控制系统来管理，团队成员编辑文件之前不需要锁定文件，这样有权限的人随时可以修改自己想修改的文件，提升团队整体效率。 

当不同的人修改了不同的文件，系统能够自动合并不同人的更改。

当不同的人修改了同一文件的不同部分，它也能够自动合并这些更改到一个文件中。

只有当不同的人修改了同一个文件的同一个部分，才会发生冲突。系统会提示并提供工具让成员手动合并更改。

在Git中，提供了代码审核的支持。当一个开发人员完成他的代码编写工作，想要让代码合并到产品中，通常是发起一个代码审核请求，叫做Pull Request。 这个审核工作通常由资深的软件工程师、架构师或者开发经理进行审核，审核通过代码就可以进到产品代码中。 

对于文档工作

上边提到的功能，对于文档都适用。 

- 2 -

创作

软件开发工作通常在集成开发环境（Integrated Development Environment，简称IDE）中进行。集成开发环境的产生源于对软件开发过程中繁琐和复杂任务的简化和整合需求。在过去，开发者需要使用不同的工具来完成代码编写、编译、调试和部署等任务，这会导致工作效率低下、容易出错。为了提高开发效率和简化工作流程，集成开发环境应运而生。

常见的集成开发环境有VS Code、Eclipse、IntelliJ等。

（1）代码编辑器

IDE提供了一个强大的代码编辑器，具有语法高亮、自动补全、代码折叠、代码格式化等功能，帮助开发者提高编码效率。

（2）编译和调试

IDE集成了编译器和调试器，可以直接在IDE中编译、运行和调试代码。开发者可以设置断点、查看变量的值，帮助定位和修复bug。

（3）项目管理

IDE可以帮助开发者创建、组织和管理项目。它提供了项目文件夹、文件导航、项目依赖管理等功能，方便开发者对项目进行整体管理。

（4）版本控制

一些IDE集成了版本控制系统，如Git。开发者可以在IDE中进行代码提交、分支管理、代码合并等版本控制操作，提高协作效率。

（5）代码重构

IDE提供了一些代码重构的功能，如重命名变量、提取方法、提取接口等，帮助开发者优化代码结构和维护性。

（6）自动化测试

一些IDE集成了自动化测试工具，可以帮助开发者编写和运行各种类型的测试，从单元测试到集成测试，提高代码质量和可靠性。

（7）文档生成

IDE可以根据代码注释自动生成文档，如API文档。这样开发者可以更方便地为代码编写文档，提高代码的可读性和可维护性。

（8）插件扩展

IDE通常支持插件扩展机制，允许开发IDE没有的功能来扩充IDE的能力。

对于文档工作

对于文档工作，IDE的很多功能用不到。IDE可以用来编写文档，不过显得太重了，而且有些期望的功能可能没有。 

如果文档是Markdown格式，可以选择Typora、VS Code、MarkdownPad这样有针对性的编辑器。

如果是XML格式，则可以选择Oxygen XML Editor, Arbortext Editor, XML Spy这样的编辑器。 

- 3 -

发布

为了提高软件的可用性，软件开发团队需要提高软件打包发布的频率。每次发布软件都手工打包已经不能满足要求，所以人们设计了持续集成工具。简称CI - Continues Integration。用来来定时执行发布操作或者根据情况触发发布操作。持续集成像是建立了一个流水线一样，分成不同的步骤，每一步使用不同的工具执行不同的任务。 

（1）版本控制整合

持续集成系统能够与版本控制系统集成，如Git、SVN等，自动拉取最新的代码进行构建和测试。

（2）自动化构建

持续集成系统可以通过自动化构建工具（如Maven、Gradle等）自动构建项目、编译源代码、生成可执行文件或部署包。

（3）自动化测试

持续集成系统可以自动执行各种测试，如单元测试、集成测试、端到端测试等，确保代码的质量和稳定性。

（4）静态代码分析

持续集成系统能够进行静态代码分析，检查代码中的潜在问题、代码风格违规、安全漏洞等，并生成相应的报告供开发者参考。

（5）编译错误和测试失败报告

持续集成系统会及时检测编译错误和测试失败，并生成相应的报告，开发者可以通过这些报告快速定位问题并进行修复。

（6）自动化部署

持续集成系统可以将构建好的代码自动部署到目标环境，如测试服务器、预生产环境等，减少人工操作的繁琐和错误。

（7）实时监控和通知

持续集成系统可以实时监控构建和测试的状态，一旦出现问题，可以通过邮件、短信等方式及时通知相关团队成员。

（8）可视化报告

持续集成系统能够生成可视化的报告，展示构建和测试的结果、覆盖率等指标，方便团队成员和管理者进行项目监控。

对于文档工作

为了提高文档的可用性，文档团队同样需要提高软件打包发布的频率。

代码过程中的编译、测试的逻辑对文档不能直接使用。

通常文档发布的过程是这样的：

1. 从Git拉取最新版本的文档

   持续集成工具一般都有从Git拉最新文件的功能。 

2. 对文档进行质量检查 （可选）

   可以集成Gramaryly、Language Tools等文档质量检查工具。

3. 文档发布打包

   对于是Markdown, RST等格式，使用框架的发布功能（如Hugo、Sphinx的发布功能）进行发布。 

   对于DITA格式，通常是集成DITA-OT来做发布。 

4. 自动部署

   对于文档，这步操作通常是拷贝文件。将发布好的文档从持续集成服务器拷贝到另外一个地方。 

   拷贝的目的地通常是人们可以通过浏览器访问得到的地方，比如：帮助中心。 

当这些工具就位以后，效果是这样的：

• 文档人员编写好文档，提交到Git服务器。Git服务器接收到有人提交了文档，自动触发文档打包和发布任务。

• 每天晚上12点，持续集成系统自动发起文档打包和发布任务。 

- 4 -

消费

不同类型的软件，让人们使用的途径不一样。对于桌面应用程序，用户需要安装到自己电脑上。 对于基于Web的应用程序，通常只需要在服务器端安装和更新，用户使用浏览器就能使用。

文档最接近基于Web的应用程序，所以就以这种类型的软件来说一说。

（1）Web服务器

Web应用程序通常安装在Web服务器中。用户使用系统的过程就是使用浏览器与Web服务器进行对话的过程。 常见的Web服务器包括Apache、Nginx和Microsoft IIS等。

（2）数据库管理系统

数据库管理系统用来存储和管理应用程序的数据。流行的选项包括MySQL、PostgreSQL、MongoDB、Redis等。

（3）日志和监控工具

日志和监控工具用来收集和分析应用程序的日志和性能数据。在系统出错的时候，日志能给分析人员有用的信息。分析程序则可以给运维人员提供系统运行的情况、用户对系统的使用情况的信息。常见的选项包括ELK Stack（Elasticsearch、Logstash、Kibana）、Prometheus、Grafana等。

对于文档工作

用户访问文档与用户使用软件相比要简单一些。通常我们将打包好的文档放到Web服务器中，用户就可以从电脑、手机上访问。 

日志和监控工具通常给到运维的同事，确保文档服务持续可用。 

分析工具对于文档团队很重要。如果文档中加入了访问跟踪，那么文档团队可以看到哪些文档、在什么时候、被从哪个地方来的用户访问了、在这个文档上停留了多久。可以了解哪些文档被访问得最多，哪些文档从来就没有人访问。文档团队可以对文档的使用信息进行分析，从而有针对性地改进文档。