开源文档的五个趋势

Shaun McCance

image

我在开源文档这方面做过很长时间。在过去的二十年里，关于创作和出版方面的看法改变过很多次。有些趋势看起来是在兜圈子，比如说语义标记的流行。最近的趋势则是文档向代码靠拢，即所谓的文档如代码。我们来看看文档趋势的几个大方向。

1. Git

当我最开始在GNOME做文档工作的时候，我们用DocBook写文档并与代码一起存在CVS里。现在GNOME用Mallard写文档并用Git管理。虽然文档格式和工具始终在变化，文档一直如代码一样存放在版本管理系统中。

很久之前就做的事情称之为趋势有点奇怪，但是在Git出现之后确实是有些东西改变了。Git大概是二十年前出来的分布式版本管理系统。很多人并没有掌握它，他们仍然沿袭CVS或SVN的方式来使用Git。文档编写者也在不断熟悉Git，他们建立开发、临时、产品等分支，合并不同人贡献的文档，这在几年前并不寻常。

Git不是唯一的一个分布式版本管理系统。还有Bazaar和Mercurial等，写作者也能象Git一样使用这些工具。但是因为有众多流行的Git托管网站所以大多数人还是在讨论Git使用上的问题。

软件文档行业上是开源主导整体的趋势。看一下技术写作论坛，里面都是各个行业的人们想要了解如何有效的过渡到Git上。过去他们可能是将文档直接存于公司网络或者使用专有的系统来管理。Git及类似工具极大地改变了整个软件行业处理文档的方式。

2. 轻量语言

文档编写的格式有很多种选择。有SGML然后是XML语法格式；有TeX和troff的各种变体；有字处理、版式工具和各种协助创作软件的文件格式；有各种不同wiki和内容管理系统的内部格式；有HTML。还有一批的轻型标记语言被设计出来以便于在文本编辑器里输入。

人们逐渐选择轻量级的标记语言有多种原因。它们通常便于编写简单版式的东西，它们能更好的由版本控制系统管理，它们能降低新人加入的门槛——但是也不要指望单靠改变文档格式就能让很多人参与到你的项目中...

轻量标记语言也有自己的弱点，跟它们相关的工具使用范围有限，并且通常不能提供其它工具所需的数据模型。它们也并不支持太多的语义信息。如XML则不然，有大量工具可以用来做翻译、校验、链接检查、状态报告、各种类型的测试和数据提取。轻量格式中很少有这些工具，所以虽然轻量格式降低新人的准入门槛，它们也对资深人员树立了新的问题。总要有所取舍。

现在最流行的三种简便格式是Markdown，AsciiDoc和reStructured Text。
Markdown最简单提供的功能也最少，基本满足大多数基本的文档需求。Markdown有很多略有不同互不兼容的风格，看你使用什么样的处理工具。
AsciiDoc支持更多的语义和类型，它原本是作为DocBook的前端，但现在已发展成为独立并支持多种输出格式的语言。
reStructure Text源自Python社区，并且很长时间内只在Python项目内使用。它之所以流行起来是因为一些文档托管网站，如Read the Docs。

3. 静态网站生成

五年前的趋势是用wiki和博客平台来建立文档站点，搭建容易也利于分享。有些人甚至开放自己的wiki给匿名用户。现在则是在版本控制系统里保存文档，编译和发布几乎都是静态HTML文件的站点。

静态站点由来已久。我大学毕业的第一份工作就是在一家软件公司用内部工具编译和发布成百上千页的文档。但现在静态站点逐渐在各种项目中流行起来有几个原因。

首先有很多现成好用的静态站点生成工具。象Middleman和JekyLL，跟wiki/博客一样配置简单。除非有特别的要求，你基本上不用维护自己的生成工具。这些工具在网站开发者和技术作者中已蔚然成风。

另一个原因是越来越多的技术人员选择使用代码托管网站。wiki的一个好处是任何人不用安装什么东西就可以编辑它。如果你的文件存放在GitHub上的话，其他人就能直接浏览器里编辑并给你提交合并请求。

4. 持续集成

持续集成是连接趋势的重要部分。你可以用简单的格式写文档，放到Git里然后通过Git托管服务在页面上编辑，直接发布它们。依靠持续集成甚至不需要人来启动发布过程。你可以像使用wiki一样在每个提交后自动发布。

有些项目比较谨慎，它们只在产品分支上发版。持续集成做了那些琐碎重复的事情，你也可以自动发布开发分支的阶段性文档站点。

持续集成并不仅仅意味着发版。项目可以利用它来做文档的校验和链接检查，给出状态和覆盖率报告等。

5. 文档托管服务

虽然持续集成让自动发布文档比之前容易很多，不过托管网站几乎包办了所有事情。告诉他们一个Git仓库，他们会自动编译、发布、托管你的文档。最著名的例子是起源于Python社区的Read the Doc，它的易用性适合各种类型的项目。

免费文档托管网站如何盈利还有待观察，运营这样的网站人力和费用上花费不菲。如果这些网站无以为继，我们就只能另寻他处。我鼓励每个人都能在资金上为它们尽一份力。

我相信托管服务会走下去，人们总能找到问题的解决方法。我也看到托管服务对非开源软件开始收费。开源在过去二十年里引领了文档技术的道路，也将继续如此。