转载

开源文档的五个趋势

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 。