为什么引入devops_DevOps可以为您的文档做什么？

为什么引入devops

在上一篇有关内容策略的文章中，我们介绍了围绕技术文档发生的哲学变化，并讨论了关心用户的新颖有趣的方法。

现在，我们对谁，什么，何时，何地以及为什么编写文档有了所有深刻的了解，让我们看看如何实践我们的讲道，并将所有这些非常有用的内容提供给渴望的读者。 对我来说，这意味着DevOps for Docs 。

是的，DevOps。 这个词发动了上千场大战。 就个人而言，我对火焰战争过敏，如果我作为Scrum Master（退休）的工作教会了我任何东西，那实际上是由您决定如何实施DevOps的：满足您的需要，不必担心自己的不满意。 t，只要您的心在正确的位置！

您的个人DevOps宣言

多亏了DevOps的灵活定义，所以有很多方法可以分解和组合这些实践。 幸运的是，由于我们的主要输出是散文而不是代码，因此docsphere可以提供更简化的细分。

我再次查看了开源社区和Red Hat文档团队在此领域中的工作，现在将尝试将Docs的DevOps细分为以下几类：

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

我将要列出的一些实践和工具已经存在了很多年，而另一些实践和工具才刚刚开始在文档领域引起人们的关注。 让我感到兴奋的是，作家可以利用我们工程学同行的所有现有知识，技能和工具，为渴望的用户提供快速，流畅的内容交付。

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

统一工具链

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

开源技术在推动这项工作中发挥了关键作用，因为对快速，精简和集成文档的需求创建了整个内容创作和发布工具系列，这些工具可以很好地与我们编写的代码配合使用。

如今，在大多数文档的核心中，您都可以找到以一种或多种我们可以使用的标记语言编写的源文件，例如DocBook XML，Markdown（所有31种版本），AsciiDoc和reStructuredText。 这些带标签的文本文件通常是通过Git进行源代码控制的（有或没有GitHub或GitLab的帮助），这是大多数开源社区以及Red Hat对其代码使用的源代码控制平台。

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

在Red Hat和其他大型企业中，要记录多个产品以及编写团队来解决问题，这意味着我们需要进行一些额外的检查和权衡，以确保我们的文档在所有开发阶段都是理智的。 值得庆幸的是，我们有一群充满激情和才华的人才，他们具有认真的开源动力，不仅可以改善我们的内部流程，而且可以帮助我们将尽可能多的工具链与我们支持的开源项目所使用的工具链保持一致。

这就是我们最终与Jenkins部署持续集成（我们可以为文档创建CI的原因！）的方法，该方法不仅在每次提交时检查整个产品文档库中是否存在断开的链接和其他错误，还生成了我们可以生成HTML和PDF输出Jenkinscat用户界面查看。 放入基于Publican的解析器，该解析器将DocBook和AsciiDoc源文件处理为所有输出，并具有统一的外观，自动发布到客户门户，使用GitLab合并请求和内容评论，您将拥有一个非常扎实的工具链。

在自动化方面，不用说API文档非常感谢JavaDoc，Sphinx auto-doc和AsciiDoctor之类的工具。 最近，似乎对文档的单元测试风靡一时，而不仅仅是代码示例。 海明威和艾默德（Emender）等新兴工具无法为您解决语法问题，但它们会分析您的内容并报告常见的语言故障，例如复合句，歧义动词和被动语态。

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

持续交付

与它的工程对应物不同，此原理的docsphere实现更加侧重于内容的异步发布，这基本上意味着我们可以将内容交付与软件交付分离。

自由！ 随时随地发布内容的自由，尽可能做到敏捷的自由（有时比我们的工程技术同行更敏捷）。 可以自由地将补丁推向生产环境，并且可以对以前发布的内容进行增强。

那些为开源项目做出贡献的人可能会兴奋不已，因为发布文档补丁程序就像编辑Wiki页面一样简单，但是在企业界，这是非常重要的事情，而这种方法又是人们钟爱的原因深受社区欢迎的开源公司。

在Red Hat，我们所有的文档都可以在Red Ht客户门户网站上公开获取官方产品版本，这意味着，每当我们修改内容时，我们要做的就是重建本书并推送解决方案。 内容策划已成为我们工作的自然组成部分，我们在计划任务时尝试平衡未发布和已发布的内容创作。 当人们不得不匆忙完成Heartbleed或Poodle引起的文档修复时，这种做法也非常方便，该修复通常适用于许多产品，因此也适用于书籍。

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

合作

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

那么我们应该和谁合作呢？ 对于初学者，涉及软件交付的每个人。 开发人员，测试人员，产品经理，设计师，支持工程师，翻译人员，我的天哪！ 我们全都在一起，作为一个产品团队，或者至少通过增加团队之间的沟通，可以从中获得很多收益。 而且，不要忘了用户本身，从开源社区成员到企业客户和面向客户的团队。

大多数开源社区已经利用具有不同程度的代码审查和社区治理的代码贡献工作流，并将这些实践也越来越多地应用于文档中。 诸如Mozilla Developer Network之类的项目展示了如何在内容社区中实现协作和社区的开源软件原理，并且OpenStack社区文档登录页面实际上显示为“由社区提供支持的文档被视为代码一样”。

开源项目中的内容协作之路仍然漫长（并且正在建设中），但在下一篇文章中将有更多有关此方面的信息！

现在，在所有发行计划和产品管理会议中，Red Hat的内容策略师均具有正式席位并进行投票，并与发行过程中每个角色的代表一起。 除了内部利益相关者外，我们还实施了闭环计划，直接从客户处或与技术客户经理，支持交付经理和其他面向客户的团队合作，收集有关我们文档的反馈。

这种类型的客户协作对我们来说还很陌生，但我有信心，它将帮助我们优化内容策略计划，并与持续交付原则配合使用，将使我们能够快速向客户交付内容增强和修复功能，他们正在从用户演变为贡献者。

下一步是什么？

现在，我们有了大部分难题。 我们说服经理或项目委员会，有价值的内容胜于全面的内容，并且我们建立了所有技术来支持平稳的内容交付。 剩下的就是让一些人写内容，对吗？

好吧，这取决于。 当您的职位以一种或另一种方式包含“作家”一词时，这就是您的期望。 但是，您如何应对一支起伏不定的开源贡献者大军，他们基本上自愿花时间为您的项目编写代码，而又没有时间，动力或对他们的语言技能的信心来编写您一直在谈论的所有这些文档？

在下一篇文章中，我将汇总来自docsphere的一些工作，并分享一些我对此的一些中等至疯狂的想法。 同时，我很想听听您关于如何在内容创作中实施DevOps实践的一些想法和故事！

文件
碟

本文是Rikki Endsley协调的Doc Dish专栏的一部分。 要撰写本专栏文章，请提交您的故事创意或与我们联系 。

翻译自: https://opensource.com/business/15/7/documentation-devops

为什么引入devops