开源文档的五个趋势

开源文档的五个趋势

Shaun McCance

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

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，它的易用性适合各类类型的项目。

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

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