Doc as Code (1)：起源

 作为技术传播从业者，你一定听说过Doc as Code，中文大家叫做文档代码化。

近年来，这个词在技术传播行业传开了。也许是在某个大会上，也许是在某篇文章中，再或者是在与同行的讨论群里，不管是从哪里，反正是知道了这个词。

Doc as Code到底是什么？它有什么特点？是否该采用这种方法？具体怎样做？我们来聊聊这个话题。

因为东西很多，咱们分成多篇文章，这样轻松一点。

- 1 -

什么是Doc as Code

这里的Doc应该翻译成“写文档”而不是“文档”，Code应该翻译成“写代码”而不是“代码”，这样Doc as Code翻译成中文是：像写代码一样写文档。所以“文档代码化”这个翻译大龙觉得并不太准确。

Doc as Code起源于软件行业的文档，是指用开发人员编写代码和发布软件相同的工具和流程来编写和发布文档。

写代码是软件工程师的主要工作，软件工程师更愿意把他们的时间花在研究需求、算法、编写和调试代码等软件开发活动上。其他工作则是能“偷懒”就“偷懒”。事实上，研发经理通常支持软件工程师的这种“偷懒”，这样能将时间花在刀刃上。比如：支持工程师制造工具来自动化完成工作，而不是重复地做某件事情，这有时是软件工程师创造力的来源。

软件工程师对生产可运行的软件兴奋不已，但对于写文档不一定有兴趣，所以很少有开发人员有意愿去为了写文档学习和使用一套新的系统。他们希望用自己熟悉的工具、熟悉的流程来写文档，这就导致了这种方法的产生。

根据Tom Johnson博客介绍(1)，Doc as Code在2010-2015年左右开始流行起来。因为一些软件开发人员觉得内容管理系统（CMS）系统过于复杂的和臃肿，它包含许多不必要的模块和基础设施。这使得写文档和将其发布成网页这样的简单任务负担过重。2008年，有一个软件开发人员叫Tom Preston Werner，他是GitHub的联合创始人，也是早期使用Docs as Code方法的开发人员之一。他在写博客时的顿悟，让他开始尝试Docs as Code这种方法写文档。

Doc as Code是一种方法，它并不限定使用某一具体工具来编辑和发布文档。

- 2 -

Doc as Code的特点

因为是使用写代码的工具和流程来写文档，所以文档也和代码类似。Doc as Code有这些特点：

• 使用纯文本文件来写作，而不是像MS Word这样所见即所得的格式
  Doc as Code使用纯文本文件作为文档的格式，格式包括：Markdown、reStructuredText（rST）、XML等。

• 使用Git、SVN等版本管理工具来管理文件，而不是使用数据库来管理
  Doc as Code使用版本管理工具，通常包括包括版本管理、分支、合并等功能。

• 使用持续集成工具来定时发布和打包文档
  持续集成的英文叫CI（Continue Integration），用来定时做文档发布和打包工作。

• 使用静态站点生成器（如Jekyll、Hugo等）构建web输出

• 使用开发人员用来审查代码的方式(Pull request)来审核文档。

- 3 -

我Doc as Code的经历

N年前，大龙在外企带领产品研发团队开发软件产品，这些软件产品供全世界范围内航空公司人员使用。我们的软件3个月发布一个大版本，中间如果发现问题，还会发布临时版本来修复问题。

当时，我们的团队使用的是Java编程语言，使用Subversion（也就是SVN）来管理软件源代码，使用Jenkins来做持续集成，每天晚上自动对软件代码进行编译、打包和测试。

我们产品的文档是这样编写、管理和发布的：

• 使用符合DocBook格式的XML文件编写
  DocBook是类似于DITA的一种基于XML的文档标准。

• 使用Arbortext Editor编辑器来编写内容
  因为我们的产品是基于PTC Arbortext Editor的，所以顺便就使用它来编写XML文档了。

• 文档内容放在SVN中进行版本管理

• 使用Arbortext Publish Engine发布文档
  在Arbortext Editor中写好文档以后，调用发布引擎的发布功能将文档发布成PDF和HTML格式。

  我们使用Arbortext Styler根据公司风格给文档定制了公司logo、首页、目录、页眉、页脚等样式，这样发布的文档就有公司的风格了。

  发布好的文档被打包生成帮助中心。

• 帮助中心与软件集成
  当安装软件的时候，帮助中心被一同安装。用户使用软件的时候在界面上点“帮助”菜单，系统会显示相关的帮助文档了。

那时候我们并不知道有Doc as Code这个词。今天来看，当时使用的就是Doc as Code这种方法嘛，这种方法对于中小型团队确实是简单实用。

在软件团队，不用引入新的工具、新的方法，就是使用软件开发现成的工具和流程写文档，一切都很熟悉和自然。

近年来这种方法被很多公司所接受，国外有Google、ServiceNow等公司，国内有阿里云、PingCAP等公司，以及众多的开源软件公司。除了软件行业，众多行业的文档团队也开始尝试这种方法。

既然是像写代码一样写文档，那么下一篇我们聊一聊软件公司到底是怎样编写、管理代码以及怎样发布软件的。

- 4 -

参考

(1) Docs as Code: 

https://idratherbewriting.com/trends/trends-to-follow-or-forget-docs-as-code.html

访问摩拿官网联系我们