开源文档领域出现的五项发展趋势

译文
开发 项目管理
未来甚至有可能出现专门面向专有软件的付费型文档托管服务。过去十年来,开源项目已经引领了文档技术的发展道路,相信其将在未来继续发挥重要作用。

【51CTO.com快译】我个人有着多年开源文档相关经验,而过去十年中此类创作与出版的方式发生了巨大变革。其中某些趋势似乎是种循环,例如评议标记的再度流行。而有些则属于新兴趋势,例如尽可能拉近文档与代码间的距离,很多人将其称为文档即代码。下面,我将总结这一领域中出现的五种发展趋势。

[[179287]]

1. Git

在最初开始参与GNOME项目的文档相关工作时,我们使用DocBook进行文档编写并将其同代码一道存储在CVS库内。如今,大多数GNOME文档开始由Mallard编写并存储在Git库中。尽管格式与工具有所变化,但将内容存储在版本控制方案内的作法仍然延续了下来。

有些朋友可能会奇怪,为什么这种长久以来的习惯仍然会被视为趋势?这主要是因为Git的出现。Git是一套分布式版本控制系统,大约诞生于十年前。当然,目前仍有人在使用分散式版本控制系统,但Git的主流地位仍然不可动摇。正是由于Git的普及,开发、分段与分支型生产方式为大多数人所接受,而这也是近年来值得关注的重要趋势。

Git当然不是惟一的分布式版本控制系统选项,我们也有其它方案可以尝试。不过Git仍然占据着大部分比重,这很大程度上利益于Git托管站点的流行。

这一趋势已经引导了整个软件文档领域的潮流。过去,人们无法通过网络驱动器存储自己的资源或者被迫使用专有型管理系统,但现在Git已经彻底改变了整个软件行业的文档处理方式——而且这是一种可喜的改变。

2. 轻量化语言

在文档源格式方面,我们总是拥有多种选项。语义XML格式、SGML格式、TeX方言以及troff方言等等。另外,还有面向文字处理、页面布局以及协助创造的其它源格式选项。一部分轻量化标记语言在设计中甚至专门进行了简化,旨在优化文本编辑器中的输入方式。

轻量化标记语言的兴起有着多种原因。其通常更易于编写,而简单正是每个人都乐于看到的效果。由于大多数轻量化语言面向行,因此其能够在版本控制系统中良好起效。其也能够有效降低新晋贡献者的入门门槛,当然大家应当谨慎变更源格式,否则很多贡献者可能因为无法适应而退出。

轻量化标记语言也有着自己的短板。能够与之协作的工具往往比较有限,且其通常无法提供编写其它工具所需要的数据模型。其亦往往无法提供充足的语义信息。以XML格式为例,其中包含大量用于翻译、验证、链接检查、状态报告以及测试与数据提取的工具,而这些工具目前在轻量化格式中并不普及。因此尽管轻量化格式能够降低新晋贡献者的上手难度,但总体来讲仍然算是有得有失。

目前人气最高的三种轻量化格式分别为Markdown、AsciiDoc以及reStructured Text。Markdown最为简单,但其能够提供绝大多数基础文档功能。另外,其还提供多种尚有兼容问题的选项,具体取决于您实际使用的处理工具。AsciiDoc拥有更多语义以及更多元素类型。其最初专注于打造DocBook的前端版本,但如今已经开始原生发展并支持多种输出格式。reStructuredText来自Python社区,其发展速度极快并在不少托管站点中得到采用。

3. 静态网站生成工具

五年之前,当时的趋势是利用维基与博客平台创建文档站点。这类站点易于设置,并允许人们更为轻松地进行贡献。一部分用户甚至建立起自己的维基以进行匿名贡献。然而如今,趋势转为利用版本控制系统保存源代码,而后通过大量静态HTML文件实现站点的构建与发布。

生成静态站点并非什么新鲜事物。我的第一份工作就是为某家软件公司开发内部工具,用以构建并发布包含无数页文档内容的静态文件。不过目前静态站点已经在各类规模的项目当中得到普遍采用,而具体原因分为以下几点。

首先,现成的静态站点生成工具越来越多。Middleman与Jekyll都能够轻松实现维基或者博客的部署工作。除非大家有特殊需求,否则直接使用现成工具即可达成目标。

另一个原因在于,以静态站点实现的源托管站点易于使用,且正有越来越多技术人员选择这类方案。如果大家将全部源文件存储在单一托管服务中,例如GitHub,那么任何拥有GitHub账户的用户都可以通过网络浏览器进行编辑并提交其作出的修改。

4. 持续集成

持续集成已经成为将以上趋势进行维系的关键。大家可以利用简单格式编写自己的文档,将其存储在Git中并通过Git托管服务进行在线编辑,而后发布至站点当中。利用持续集成机制,大家甚至不需要人工进行发布处理。如果愿意,大家甚至能够自动向master提交变更内容,并借此实现类似于维基的管理方式。

某些项目则比较保守,即只允许由生产部门进行发布。但即使是这种以branch为源头的发布方式,持续集成仍然能够显著减少人为干预的必要性。大家也可以自动发布分段站点以实现分支开发。

当然,持续集成的作用绝不仅限于发布。各类项目皆可利用其自动进行文档测试,或者根据状态及覆盖范围生成报告。

5. 托管文档服务

虽然利用持续集成实现文档自动发布已经相当便利,但如今的众多托管服务在此基础上作出了进一步简化。只需要将其传递至Git库,即可自动完成构建、发布以及文档托管。

不过免费文档托管站点是否能够实现盈利还有待观察——毕竟运作这样的站点需要投入成本及时间。如果站点无法保持一定的质量水平,人们会选择将文档托管于其它平台。而如果您喜爱自己当前的托管方案,请考虑以捐款形式为其提供支持。

我认为托管文档服务的趋势将进一步持续。未来甚至有可能出现专门面向专有软件的付费型文档托管服务。过去十年来,开源项目已经引领了文档技术的发展道路,相信其将在未来继续发挥重要作用。

原文标题:5 trends in open source documentation   原文作者:Shaun McCance

【51CTO译稿,合作站点转载请注明原文译者和出处为51CTO.com】

责任编辑:王雪燕 来源: 51CTO
相关推荐

2017-12-29 08:45:00

大数据语言推荐系统

2015-10-14 16:10:45

技术从业者

2023-01-03 10:52:26

IT领导者IT自动化

2010-12-13 16:13:43

移动未来发展趋势

2009-12-29 09:24:16

WEB开发

2013-11-20 09:18:55

IT领域2014发展趋势

2012-04-11 09:41:40

2022-01-17 08:00:00

云安全网络安全云泄露

2021-08-26 14:22:13

区块链数字钱包比特币

2023-03-02 08:47:31

IT预算热点

2022-03-09 22:48:28

前端开发Web

2022-10-21 10:09:34

2022-01-18 09:01:39

前端技术编程

2019-06-04 07:00:37

2011-12-01 09:07:31

2022-01-07 13:42:07

云计算云计算环境云应用

2022-03-08 20:59:17

光通信有线通信光传输网络

2023-06-09 19:03:35

开源组织

2018-04-24 15:25:15

物联网发展趋势互联网

2022-02-13 00:20:44

区块链加密货币技术
点赞
收藏

51CTO技术栈公众号