软件技术文档代码化现象

1.7. 软件技术文档代码化现象#

文档代码化，英文是Docs like Code，是指采用开发软件的方式来开发文档，最后表现出文档和代码类似的现象。 本文主要分享，Docs like Code 作为一种文档开发方案的优缺点和应用场景等。

在Stack overflow 2016年的程序员调查中发现：缺乏文档已经是程序员日常工作中，排名第二的难题。 在Stack overflow 2017的程序员调查中发现：通过官方文档自学，是程序员的首选学习方式。 与消费者对待文档的态度不同，专业级用户对文档的重要性有着充分的认识，在学习和解决问题时，技术文档是极为重要的参考资料。

我自己在学习使用Github和Python等工具时，也是参考了大量的官方文档。 而且在阅读Github的帮助文档时，由衷地感叹其文档之简洁，层次之分明。 在官方文档的引导下，很快便能上手使用Github。 在技术写作行业，我们常常说文档是产品不可分割的一部分， 但是在传统领域，由于文档常常是独立存在的一个实体，用户不自觉地便会把产品和文档分开对待。 在软件产品中，由于软件和文档耦合紧密，文档真的成为了软件不可分割的一部分。 很多时候，程序员是否选择使用某工具，完全取决于该工具是否有完备且高质的文档。

最近使用了很多软件工具包，发现很多软件的文档质量都非常高，与此同时也发现很多技术文档的模样都较为类似。 出于职业敏感，直觉上感觉应该是使用了某种框架，至少是受到了某个学派的影响。 于是做了一些调研，发现果然如此。 欧美多个技术写作会议上都在讨论文档代码化(docs like code)的现象，而且俨然成了技术写作的buzzword，很多人甚至宣称这是软件文档的未来趋势。

接下来便和大家一起聊聊，文档代码化现象，后文会主要使用Docs as Code来表示这一现象。

1.7.1. 典型的软件文档#

Tensorflow文档

TensorFlow关于Image Recognition的文档，非常经典的技术信息呈现方式：

  • 左边是全部文档的结构，

  • 中间是正文部分，

  • 右边是当前文档内部结构导航。

纲举目张，简洁好用。开发人员会非常喜欢这样的信息呈现。

如果打开网站右上角GITHUB的repo链接，在tensorflow/tensorflow/docs_src路径中便可以找到该文档的原始文件,其实是一个markdown文件。

听过Google技术文档团队的分享，原先Google内部文档原先也有很大的问题， 后来启动了g3doc文档项目，并采用 docs like code 理念改造了文档流程，之后文档整体才有了很大的提升。

PingCAP文档

PingCAP是一家开源数据库公司，其文档团队目前主要都是北大计算机辅助翻译专业的毕业生。文档也是典型的左中右三栏结构。

PingCAP 的核心产品 TiDB （一款开源分布式数据库）的技术文档也可以在Github上公开访问，有兴趣的可以访问了解一下。 其原始文件也都是通过Markdown写作的。下方是其文档repo的结构截图。

这样案例不胜枚举，有兴趣的还可以继续点击下方的链接，进而查看他们的文档，整体结构都非常类似。

  • Githup Help

  • Readme Docs

  • Openstack

  • CISCO Metacloud

  • GRAV

如果想了解更多类似这类帮助文档，这里还有一份更全的文档列表。

1.7.2. 什么是文档代码化#

在上方的示例中，相信大家已经可以发现：文档和代码你中有我，我中有你，甚至会认为文档项目就是软件开发项目。没错这就是文档代码化，或者是英文说法的 Docs like Code 或 Docs as Code。

在与从业人员交流，还有文献调查的基础之上，我发现 Docs like Code 现象有如下特征：

  • 开发方式一致。软件代码在开发的时候，基本流程是：写代码、审查代码和部署代码，文档在开发时候，也会采用和代码开发相同或类似的方式。

  • 集成在开发流程中。文档开发作为软件开发的一部分，也是最终产品的一部分，其开发过程是嵌入在整个软件开发过程中的。

  • 开发工具一致。文档写作时，一般使用代码编辑器如Eclipse或Visual Stuido Code，而不会用诸如Word或FrameMaker这类工具。

  • 使用标记语言。一般使用轻量级标记语言如Markdow, reStructedText或ASCii等，或更复杂的XML等标记语言。

  • 文档和代码共同存储。例如使用Github，代码和文档会在同一个repo下，开发人员和文档工程师都可以访问。

  • 版本控制。一般使用git或svn这类工具进行版本管理。

  • 网站发布自动化。内容写作完成后，一拉webhook就能自动发布为帮助页面。

1.7.3. 文档代码化的优势#

  • 产品和文档一致性高。因为产品和文档在同一个流程和工具中开发，文档和代码不一致的现象会减少。代码有更新的时候，文档也可以快速更新。

  • 程序员贡献度高。程序员在编码的同时，可以不离开当前环境，直接参与文档。因为操作容易，所以大大提高了程序员的贡献度。例如在Twitter的实践中，一些程序员甚至能贡献第一版的文档草稿。

  • 成本低。与工具厂商提供的成套解决方案想比，这种工作模式基本不增加额外成本，深受初创企业喜爱。

1.7.4. 文档代码化的工具链#

Docs like code的开发模式因为借鉴软件开发的模式，其文档工具链与软件开发工具链非常类似。具体而言，如下工具非常常见。

  • 轻量级标记语言。 因为文档融入到开发过程中，所以和代码文件类似，一般文档都会以纯文本存储内容。常见的这类标记语言有 Markdown, reStructuredText，Textile ，AsciiDoc和Org-mode等。

  • 写作工具。为了和程序员保持一致，采用的写作工具也常常和程序员选择的工具保持一致，例如采用Eclipse，Visual Stuido，Sublime等。

  • 静态网站发布工具。内容用写作工具和标记语言写好后，还需要由静态网站发布工具将其发布为最终用户可以轻松使用的帮助文档系统。常见的发布工具有，Jekyll，Hugo，Pelican，Sphinx等。这类工具也是非常多，有兴趣的可以参见：静态网站生成器列表。

  • 版本控制。和代码一样，文档也需要经过若干轮的修改和更新。一般会使用git，svn等版本控制工具。

  • 文档测试。静态网站发布后，还需要使用QA工具对文档进行测试，对齐质量进行检查，确保内容发布完整、术语一致、链接正常工作、格式正确等验证性工作。

1.7.5. Docs like code 工作流#

在制定工作流之前，需要跟开发人员讨论，根据团队成员习惯，确定合适的工作流。准备工作有“

  • 确定工具链。如标记语言、写作工具、版本控制等。

  • 确定写作风格和各类规约等。

根据Github的分享，其团队的Docs like code工作流大致如下：

  • 文档团队记录需要新增的功能

  • 使用issue tracker追踪新功能

  • 在branch中写作和修订文档。

  • 文档准备好之后，merge所有的pull request.

  • 拉webhook，将所有markdown的内容发布。

  • 测试文档，确保链接正常，图片没有丢失等。

1.7.6. Docs like code方案的不足#

  • 文档的发布频率高。代码一般更新较慢，而文档则更新较多。例如更正笔误、句序调整等。有时文档在未merge的branch中，其他成员无法参与文档修订，需要等代码merge后才行。

  • 测试有限。代码会经过多轮严格测试才会发布，但是文档则难以做到相同标准。工程师甚至常常不愿意读文档，确保技术信息正确。

  • 保密性差。有一些资料需要有权限才能阅读，这种文档方式比较难实现。

  • 多格式输出困难。一般只能生成HTML，如果需要生成PDF，epub等其他式，与现有成熟文档方案想比，会复杂很多。

  • 对写作人员的要求更高了。写作人员需要学习更多的开发知识，尤其是html，css和js等方面的前端知识。

1.7.7. 总结#

整体而言，Docs like Code 的方案较为适合初创型软件公司，可以容易地生成高质量文档，而且成本较低。 如果公司还需要多种格式输出、权限管理以及翻译等其他功能，那么传统的成熟解决方案如oXygen XML，Madcap Flare， Adobe Technical Communication Suite等，可能更为适合。

参考资料

  • Limits to the idea of treating docs as code

  • The docs-like-code approach to documentation production

  • Transforming Developer and Support Documentation with Docs Like Code

  • Why we use a ‘docs as code’ approach for technical documentation

  • OpenStack Documentation Contributor Guide

目录