现代软件文档开发：敏捷时代，要像写代码一样写文档！

现代软件开发，苦文档久矣。

与传统软件的“瀑布式开发”不同，现代软件强调“敏捷开发”，小步快走，迅速迭代。

《敏捷软件开发宣言》中的价值观之一是“软件能够运行，优于详尽的文档”。这是为了敏捷需要做的妥协。这也意味着，文档必须紧跟代码，迅速迭代优化。

“苦苦追随”的文档

传统的“瀑布式开发”由于发布周期长（有时长达一年），有充分的时间准备需求文档、刻画用户旅程、完成设计文档，再基于这些资料由专业的 Tech Writer 撰写详尽的用户文档。

敏捷开发的发布周期通常为 2~6 周，在如此快节奏的项目中，传统的文档开发流程不得不砍掉大半。有时因为时间紧迫，甚至需要软件开发者直接完成用户文档的初稿，再由专业的 Tech Writer（如果有）润色。

但敏捷项目中的工程师们开发新功能、修复 bug 就够忙了，总不能把写文档排到更高的优先级吧？慢慢地，忘记更新文档、随处写文档、甚至不写文档，成了现代软件开发的常态。

据 Stack Overflow（著名开发者问答社区）2016 年的调查显示，文档质量差是软件工程师们在工作中最常抱怨的三大问题之一。文档不完整、文档找不到、文档过时逐渐成为软件工程师们面临的“三堵高墙”。

这一现象直接催生了文档代码化（也称为 Docs Like Code 或 Docs as Code）运动的兴起。具体的故事，我们从主人公小娜开始说起。

文档代码化运动

小娜是 G 司的一名 Tech Writer，因为 G 司的工程师不愿意写文档、随处（如 README、wiki、Google Doc）写文档，她尝试了各种办法，从上至下行不通，从下至上太低效。

最终她得出结论，G 司的工程师太有自己的想法，他们只做自己想做的事情，用自己想用的工具，别人不可能告诉他们该做什么。

明白这一点的小娜大受打击，沉沦几月后去了某个以文档为主题的行业会议。在那里，她偶遇了 T 司的小明。

在会上，小明说 T 司的工程师也不愿意写文档，但他们想到了一个办法，把文档和代码放在一起，让工程师们像写代码一样写文档。这成功改变了 T 司写文档的文化，从此大家都愿意写文档了。

小娜听完茅塞顿开，回去后立即招兵买马，她在内心狂吼：这次你们工程师一定得给我写文档！

经过三个月的准备，小娜在 G 司发起的文档代码化运动在工程师中大受欢迎。半年内，采纳文档代码化方式写文档的内部项目超过了 1600 个。文档代码化慢慢成为了 G 司软件文档开发的一项事实标准。

故事里的 G 司叫 Google，T 司叫 Twitter，小娜与小明相遇的大会是 Write the Docs（聚焦文档主题的行业顶级会议）。

故事来源：
- Write the Docs 2014 会议上，来自 Twitter 的 Simeon Franklin 和 Marko Gargenta 做了文档代码化的实践分享，台下来自 Google 的 Riona MacNamara 备受鼓舞。
- 次年 Write the Docs 会议上，Riona 分享了在 Google 进行文档代码化实践的成功经验。

Twitter 和 Google 先后树立文档代码化的新旗帜后，这个新颖的文档开发流程一炮而红，不少中小型公司争相模仿，文档代码化的工具链逐渐被完善。

文档代码化意味着什么

文档代码化不是一个工具，而是一种理念。这种理念决定了一套写文档的完整流程和工具链，即：

写文档与写代码的流程和工具链保持一致。

具体来说，文档代码化决定了写文档的工具：

• 纯文本标记语言（如 Markdown、reStructuredText）
• 版本控制系统（如 Git）

也决定了写文档的流程：

• 编辑文档 => 使用 IDE（集成开发环境），如 Visual Studio Code
• 存储、审校文档 => 使用 GitHub 等源代码托管服务平台
• 多人协作、管理多版本 => 使用 Git 分支
• 跟踪文档问题 => 在 GitHub、Jira 等工具上建立 Issue 追踪
• 测试文档质量、持续发布文档 => 使用 CI/CD（持续集成/交付）系统

看到这儿或许你明白了，为什么从来不喜欢写文档的 Twitter 和 Google 工程师们，如此钟爱文档代码化？

因为他们不必从代码开发环境中切换出去，不必学习任何新的东西，用自己最熟悉的 Git + Markdown + 敏捷开发流程，就能快速发布漂亮的文档。

文档代码化的优劣势

优势

文档代码化天生适合集成在敏捷开发流程中，拥有其他文档方案望尘莫及的“原生”支持。

个人认为，文档代码化是最敏捷的商业软件文档开发方式。一个字，就是“快”。原因包括：

• 文档任务能更早地融入到软件版本发布的流程：每个开发任务一旦被认定需要修改或添加文档，必须绑定相关的文档 Issue，在发版项目看板中一并追踪。有些公司甚至要求，如果没有文档，不允许合并代码。
• 文档作者和审校者基于 Git 命令行合作，效率更高：使用命令行界面 (CLI) 和图形用户界面 (GUI) 的效率有较大差别，具体原因见这篇文章。
• 零排版时间：用纯文本标记语言使内容与格式分离，让作者专注于写作本身。
• 文档持续、即时发布。
• 快速追责，Git/GitHub 中保留了一切文档改动、沟通、操作细节：你甚至能快速定位到文档的某一行是谁在什么时候写的。
• 方便引入自动化工具（如 bot），节省沟通、项目追踪的时间。

除此之外，文档代码化也适合实现：

• 多版本：Git branch 就是一个成熟的划分版本利器
• 多语言：采用分文件夹方式，能轻松实现多语言文档的扩展
• 多形式/平台发布：采用纯文本标记语言编写文档，适合导出成 PDF、epub、word 等多种格式，或者导出到各个内容平台

劣势

不过，文档代码化的劣势也很明显：需要一定的技术资源和开发成本。具体的技术支持包括配置前端读取 Git 仓库源、优化文档站外观、配置持续集成部署、实现内容重用等。

对于 Tech Writer 来说，还需要学习 Git 命令行工具、Markdown 等。

还有一点可能会让一些人比较恼火：简单的文档修改可能稍显复杂。比如改个错别字、链接等，也需要走一遍完整的 Git 提交、审校、合并流程。如果某个发现文档问题的人不熟悉 Git 流程，他可能不会愿意费心改文档。

文档代码化的适用场景

基于以上优缺点，我总结了文档代码化的适用场景。

场景一：采用敏捷开发的软件公司。

尤其是那些需要软件工程师先写文档、Tech Writer 后润色的公司。文档代码化是工程师们最易接受的写作方式之一。

场景二：工程师远远多于 Tech Writer 的公司。

比如 Google 有上万工程师，上千个内部技术项目，专业 Tech Writer 的配备远远不够。工程师必须自己写文档。

这种情况下，为了充分利用、检索这上千个技术项目的文档资源，必须采用一个统一的、最易于工程师上手的文档开发方式。

场景三：成本有限的公司。

文档代码化方案中有丰富的免费开源工具供使用，并且可复用代码开发的工具链、无额外购买成本。

场景四：做开源软件项目的公司或个人。

开源软件想要强大，很大程度上需要依赖社区生态。如果想要软件全球化发展，就必须靠社区的力量支持文档的多语言输出。从第一天就采用开源方式维护文档，逐渐壮大 GitHub 上的文档社区，是最好的选择。

和其他方案的对比：DITA、wiki

在文档代码化理念诞生之前，常见的技术文档解决方案有两种：基于 DITA 理念的各种内容管理系统 (CMS) 和以 Confluence、维基百科为代表的 wiki。

DITA 简介

如果你是一名 Tech Writer，你一定听说过 DITA。DITA 的全称是 Darwin Information Typing Architecture（达尔文信息类型化体系结构），它最初由 IBM 创建，是一个基于 XML 的开放标准。

DITA 是“瀑布式开发”时代当之无愧的文档界霸主，用户遍及制造业、航空、通信、医药等传统行业。

DITA 最大的优势是：

• 基于 topic 的写作：将所有信息分为概念类、任务类、参考类、故障处理类四类 topic，实现信息的最小单元，方便内容重用
• 支持同源开发：只需维护一套源文件，便可发布到不同的格式和平台
• 内容与格式分离：作者可专注于内容写作，格式转换由其他技术完成

DITA 的劣势很明显：贵、重。

wiki 简介

如果你是一名软件工程师，你一定听说过 wiki。wiki 可以理解为全开放给用户社区开发的网站或数据库，允许任何用户添加和编辑内容。

wiki 的理念是充分利用群体智慧，相信“众人拾柴火焰高”。其最大的优势是：

• 人人可编辑
• 能够快速发布迭代

wiki 的劣势有很多：

• 无审校流程，商业用户文档可能遭受恶意篡改
• 人人可编辑，结构很容易混乱
• 页面越来越多，难以维护
• 没有可定制的、漂亮的前端呈现
• 实现多版本比较困难

三种方案对比

在敏捷开发时代，一个好的文档解决文档应该提供不同于以往“瀑布式开发”时代的支持。根据这些支持，我将这三种方案一一做了对比，希望给正在考虑文档方案的同行们一个直观的印象：

该表仅供参考，不同公司应视自身体量、阶段、需求、目标等选择合适的文档解决方案。

结语

2019 年 11 月，KPMG 发布了一份主题为“敏捷转型”的报告。报告中提到，全球范围内有 91% 的 IT 行业受访者表示他们的组织采用敏捷开发，77% 的非 IT 行业受访者表示他们的部门采用敏捷方法工作。

“敏捷”日益成为一个组织迎接未来挑战的战略重点。

作为一名 Tech Writer，我不禁想，在敏捷时代到来之际，为敏捷而生的文档代码化方案是否会成为大势所趋？

文档代码化的实践中，还有种种尚未攻克的问题。我也只是看到了现代软件文档开发中，出现的一丝最佳实践的光芒。

希望未来如我的领导所言：也许我们偶然的一步，正好踏在时代的脉搏上。

作者简介：Coco，PingCAP 公司 Tech Writer。
作者说：PingCAP 在成立之初，偶然采用了文档代码化方式来管理中英双语用户文档。我入职后，在其工具流程上进行了很多优化。我的阅历有限，因为对这段历史很感兴趣，写了这篇文章，如有不当之处，敬请各位同行指正。
路漫漫，与人同行最好。

原文发布于微信公众号「阿狍杂谈」，扫描下方二维码关注，我还有更多技术写作相关的文章与你分享～