开源文档的 5 个趋势

我从事开源文档工作很长时间了。在过去的十年中，关于创作和发布的态度发生了很多转变。其中一些趋势似乎呈周期性变化，例如语义标记的流行。最新的趋势是将文档更贴近代码，许多人称之为文档即代码。让我们看看文档趋势中的几个更大的主题

1. Git

当我刚开始为 GNOME 编写文档时，我们使用 DocBook 编写文档，并将其与代码一起存储在 CVS 存储库中。如今，大多数 GNOME 文档都使用 Mallard 编写，并存储在 Git 存储库中（在短暂使用 SVN 之后）。尽管格式和工具发生了变化，但不变的因素是源代码像代码一样存储在 版本控制中。

当我们已经这样做这么长时间时，称之为趋势似乎很奇怪，但一些事情发生了变化，其中一些变化围绕着 Git 带来的东西。Git 是过去十年左右出现的分散式版本控制系统之一。有些人继续以使用 CVS 或 SVN 的方式使用分散式版本控制系统，但这并没有发挥这些系统的真正威力。文档编写者越来越精通使用 Git 的本质。他们正在创建开发、暂存和生产分支，并且他们正在合并不同的贡献。这在几年前还不太常见。

Git 当然不是唯一的分散式版本控制系统。还有 Bazaar 和 Mercurial，仅举两个例子，您会发现作者使用这些工具也具有相同的能力。但是 Git 占据了大部分的注意力，这在很大程度上归功于流行的 Git 托管站点。

开源在这个领域引领了整个软件文档行业的趋势。快速浏览技术写作论坛就会发现，整个行业的很多人都在寻找关于如何有效过渡到 Git 的信息。过去，他们可能将源代码存储在没有版本控制的网络驱动器上，或者他们可能使用了专有的管理系统。Git 和类似的工具极大地改变了整个软件行业处理文档的方式。

2. 轻量级语言

文档源格式一直有很多选择。有语义 XML 格式，以及之前的 SGML 格式。有 TeX 方言和 troff 方言。有文字处理器、页面布局工具和帮助创作工具的源格式。有各种 wiki 和内容管理系统的内部格式。有 HTML。还有一些轻量级标记语言，旨在易于在文本编辑器中键入。

人们越来越多地选择轻量级标记语言，原因有很多。它们通常更容易编写，至少对于简单的事情来说是这样。它们往往更适合版本控制系统，因为它们通常是面向行的。它们可以帮助降低新贡献者的入门门槛，尽管您应该注意不要期望仅靠源格式的改变就能吸引大量贡献者加入您的项目。

轻量级标记语言也有其缺点。用于处理它们的工具往往范围有限，并且通常不提供编写其他工具所需的数据模型。它们通常也不提供那么多语义信息。例如，对于 XML 格式，有大量的工具用于翻译、验证、链接检查、状态报告以及各种类型的测试和数据提取。对于轻量级格式，这种工具目前还没有那么广泛。因此，尽管轻量级格式可能会降低新贡献者的入门门槛，但它们也可能为长期维护设置新的障碍。与所有事物一样，总是有权衡取舍。

目前最流行的三种 轻量级格式 是 Markdown、AsciiDoc 和 reStructured Text。Markdown 最简单，但除了最基本的文档需求之外，它并没有提供太多。它也有许多不同的、略微不兼容的风格，具体取决于您使用的处理工具。AsciiDoc 提供了更多的语义和更多类型的元素。它最初专注于作为 DocBook 的前端，但它已经发展到原生支持许多输出格式。reStructuredText 来自 Python 社区，长期以来，它的使用主要限于 Python 项目。由于 Read the Docs 等托管站点的出现，它近来变得越来越流行。

3. 静态站点生成器

五年前，趋势是使用 wiki 和博客平台来创建文档站点。它们易于设置，并且为人们提供帐户以便贡献也很容易。特别勇敢的人甚至会向匿名贡献开放他们的 wiki。如今，趋势是将源代码保存在版本控制中，然后使用主要是静态 HTML 文件构建和发布站点。

生成静态站点并不新鲜。我的大学毕业后的第一份工作是在一家软件公司从事内部工具，用于构建和发布数万页文档的静态文件。但是静态站点在各种规模的项目中变得越来越流行，原因有很多。

首先，有越来越多优秀的现成静态站点生成器。像 Middleman 和 Jekyll 这样的工具与 wiki 或博客一样易于部署。除非您有特殊需求，否则您不再需要编写和维护自己的站点生成工具。静态站点生成器在 Web 开发人员中变得越来越流行，技术作家也因此受益。

静态站点更流行的另一个原因是，源代码托管站点更容易使用，并且越来越多的技术人员使用它们。wiki 的吸引力之一是，任何人都可以贡献，而无需下载任何东西或安装特殊工具。如果您的源文件存储在像 GitHub 这样的托管服务中，任何拥有 GitHub 帐户的人都可以在他们的 Web 浏览器中编辑它们，并要求您合并他们的更改。

4. 持续集成

持续集成是将之前趋势联系在一起的关键。您可以使用简单的格式编写文档，将其存储在 Git 中，并使用 Git 托管服务在 Web 上编辑它，并从这些源发布站点。通过持续集成，您甚至不需要人工来启动发布过程。如果您胆大，您可以在每次提交到 master 后自动发布，并且您将为作者提供近乎 wiki 的体验。

一些项目会更加保守，只从生产分支发布。但即使从分支发布，持续集成也消除了繁琐的人工干预。您还可以自动发布开发分支的暂存站点。

持续集成不仅仅是关于发布。项目可以使用它来自动测试其文档的有效性和链接完整性等，或生成关于状态和覆盖率的报告。

5. 托管文档服务

使用持续集成自动发布文档站点比以往任何时候都更容易，但现在有托管服务可以为您处理一切。只需将 Git 存储库传递给它们，它们就会自动构建、发布和托管您的文档。最著名的例子是 Read the Docs。最初来自 Python 社区，其易用性使其在各种项目中都很受欢迎。

免费托管文档站点在经济上是否可行还有待观察——保持这样的站点运行需要金钱和人工时间。如果这些站点无法维持一定的质量水平，人们会将他们的文档转移到其他地方。如果您受益于这些免费服务之一，我鼓励您考虑如何提供经济上的帮助。

我相信托管文档服务的趋势将继续下去。聪明人会想办法消除障碍。我也怀疑我们将开始看到针对专有软件的付费托管文档服务。在过去十年中，开源在文档技术方面一直处于领先地位，并且它将继续这样做。