DevOps 能为你的文档做些什么？

在我上一篇关于 内容策略 的文章中，我们探讨了技术文档领域正在发生的理念转变，并讨论了关爱用户的新颖而令人兴奋的方式。

既然我们对文档的编写对象、内容、时间和地点以及原因有了如此深刻的见解，那么让我们来看看如何实践我们所宣扬的理念，并将所有这些非常有用的内容交付给渴望阅读的读者。对我而言，这意味着文档的 DevOps。

没错，就是 DevOps。这个术语引发了无数的口水战。就我个人而言，我对口水战过敏，如果说我作为一名（已退休的）Scrum Master 的工作教会了我什么，那就是如何实施 DevOps 完全取决于你：取你所需，不必担心你不需要的，只要你的心意是好的！

你的个人 DevOps 宣言

多亏了 DevOps 的，嗯...灵活的定义，有很多方法可以分解和分组这些实践。幸运的是，文档领域可以承受更简化的分解，因为我们的主要输出是散文而不是代码。

我再次审视了开源社区和红帽文档团队在这个领域所做的工作，现在将尝试将文档的 DevOps 分解为以下类别

• 统一工具链
• 持续交付
• 协作

我即将列出的一些实践和工具已经存在多年，另一些才刚刚在文档领域获得关注。令我兴奋的是，作者可以利用我们工程同行现有的所有知识、技能和工具，为我们渴望的用户创建快速而流畅的内容交付。

这也意味着我们可以用我们的内容做一些非常酷的事情！

统一工具链

从源代码控制、标记语言和发布解析器，到持续集成和自动化测试，简单的文字处理器到印刷书籍的时代早已一去不复返了。还记得文档 CD 吗？那可不好看。

开源技术在推动这项工作中发挥了关键作用，因为对快速、精简和集成的文档的需求催生了一整套内容创作和发布工具，这些工具与我们记录的代码配合得很好。

在当今大多数文档的核心，你可以找到源文件，这些文件是用我们可用的多种标记语言中的一种或多种编写的，例如 DocBook XML、Markdown（所有 31 种风格）、AsciiDoc 和 reStructuredText。这些标记文本文件通常使用 Git（有或没有 GitHub 或 GitLab 的帮助）进行源代码控制，Git 是大多数开源社区以及红帽用于其代码的相同源代码控制平台。

许多开源项目在其代码附近或与其代码一起管理其文档，并且一些项目采用有趣的技巧来使发布流程与项目构建保持一致，并简化内容贡献。例如，KDE 使用一些巧妙的脚本将 Wiki 库转换为基于 DocBook 的指南，因此你可以使用简单的 Markdown 进行创作，并且仍然可以享受 DocBook 强大的发布功能。NixOS 使用 Nix 包管理器来 打包 Nix 文档，而 GitHub 使用 GitHub 来记录 GitHub。非常元！

在红帽和其他大型企业中，拥有多个产品需要记录，以及编写团队需要管理，这意味着我们需要一些额外的检查和平衡，以确保我们的文档在所有开发阶段都是合理的。值得庆幸的是，我们有充满热情和才华的人，他们拥有一些由开源驱动的强大创造力，这不仅改进了我们的内部流程，还有助于我们尽可能多地将工具链与我们支持的开源项目使用的工具链对齐。

这就是我们最终使用 Jenkins 部署持续集成的原因（我们可以为文档提供 CI！），它在每次提交时不仅检查整个产品文档库中是否存在损坏的链接和其他错误，还生成我们可以使用 Jenkinscat UI 查看的 HTML 和 PDF 输出。再加入一个基于 Publican 的解析器，它可以将 DocBook 和 AsciiDoc 源文件处理成具有统一外观和感觉的所有输出，自动化发布到客户门户，使用 GitLab 进行合并请求和内容审查，你就拥有了一个非常可靠的工具链。

在自动化方面，无需赘言，API 文档非常感谢 JavaDoc、Sphinx auto-doc 和 AsciiDoctor 等工具。最近，文档的单元测试似乎风靡一时，而不仅仅是代码示例。像 Hemingway 和 Emender 这样的新兴工具不会为你修复语法，但它们会分析你的内容并报告常见的语言错误，例如复合句、歧义动词和被动语态。

希望我们能看到对这些工具的更多贡献，因为它们可以自动化一些更繁琐的同行评审任务，并帮助我们保持一致性和简洁性。

持续交付

与其工程同行不同，文档领域对该原则的实施更侧重于内容的异步发布，这基本上意味着我们可以将内容交付与软件交付解耦。

自由！随时发布内容的自由，尽可能敏捷的自由（有时比我们的工程同行更敏捷）。推送补丁到生产环境的自由，以及向以前发布的内容添加增强功能的自由。

那些为开源项目做出贡献的人可能会嘲笑我的兴奋，因为发布文档补丁可能就像编辑 Wiki 页面一样简单，但在企业界，这是一件非常重要的事情，这种方法也是热爱开源公司的另一个原因，在开源公司中，社区的影响力非常强烈，并且受到欢迎。

在红帽，我们所有的文档都公开在红帽客户门户上，用于官方产品发布，这意味着每当我们修改内容时，我们所需要做的就是重建书籍并推送修复程序。内容策展已成为我们工作的自然组成部分，我们在计划任务时会尝试平衡未发布和已发布的内容创作。当必须紧急修复通常适用于许多产品和书籍的 Heartbleed 或 Poodle 漏洞引发的文档问题时，这种做法也非常方便。

我们如何管理所有这些异步发布周期？这取决于产品和团队。我们的一些工程团队使用类似敏捷的方法，因此文档团队可以将其迭代与他们保持一致。一些文档团队“敏捷地”独立于他们的工程团队。其他团队甚至没有使用敏捷，而是选择在发布周期的早期纳入更多内容策展任务，并在功能准备好记录时在后期进行以发布为中心的创作。

协作

“没有人生活在真空中”似乎是我最近经常重复的一句话，这是有充分理由的：没有协作，就不会有开源软件。除了以用户为中心的内容策略方法外，我们在创建文档时还必须考虑到我们所有的利益相关者。

那么我们应该与谁合作呢？首先，是每个参与软件交付的人员。开发人员、测试人员、产品经理、设计师、支持工程师、翻译人员，哦，我的天！我们都在一起，作为一个产品团队行动，或者至少通过加强团队之间的沟通，我们可以获得很多好处。而且，我们不要忘记用户本身，从开源社区成员到企业客户和面向客户的团队。

大多数开源社区已经利用代码贡献工作流程，其中代码审查和社区治理程度各不相同，并且越来越多地将这些实践应用于文档。像 Mozilla 开发者网络 这样的项目展示了协作和社区的开源软件原则如何在内容社区中实施，而 OpenStack 社区 文档登陆页面实际上写着“像代码一样对待文档，由社区驱动”。

开源项目中的内容协作之路仍然漫长（并且正在建设中），但更多内容将在下一篇文章中介绍！

红帽的内容策略师现在在所有发布计划和产品管理会议中都拥有正式席位和投票权，与发布过程中每个角色的代表并肩而坐。除了内部利益相关者之外，我们还实施了闭环计划，以收集对我们文档的反馈，直接来自客户或通过与技术客户经理、支持交付经理和其他面向客户的团队合作。

这种类型的客户协作对我们来说是相当新的，但我相信它将帮助我们优化我们的内容策略计划，并且当与持续交付原则相结合时，将使我们能够快速向我们的客户交付内容增强和修复，而我们的客户正在从用户转变为贡献者。

接下来是什么？

现在我们已经掌握了大部分拼图碎片；我们说服了我们的经理或项目委员会，有价值的内容比全面的内容更好，并且我们设置了所有技术来支持流畅的内容交付。剩下的就是让一些人编写内容，对吗？

嗯，这取决于情况。当你的职位头衔以某种方式包含“作者”一词时，这是对你的期望。但是，你如何应对一群不稳定的开源贡献者，他们基本上是自愿花费时间为你的项目编写代码，并且没有时间和动力，也没有语言技能的信心来编写你一直在谈论的所有这些文档？

在下一篇文章中，我将汇总来自文档领域的一些努力，并分享一些我自己的中等或疯狂的想法。同时，我很想听听你关于如何在内容创作中实施 DevOps 实践的一些想法和故事！

本文是 Rikki Endsley 协调的 Doc Dish 专栏 的一部分。要为本专栏投稿，请提交你的故事想法 或 联系我们。