股票代码: 836286    股票简称: 易云股份
官方微信

扫一扫关注易云捷讯官方微信

备案 |       管理控制台

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

原文链接:What can DevOps do for you documents?

作者: Mieky Ariel

翻译:李建盛

在上一篇文章内容为王,技术文档新理念中我们围绕技术文档探讨了理念的转变,以及新的、带劲的关心用户的方法。

既然我们已经拥有了对于who,what,when,where,以及why的伟大的启示,接下来,让我们看看我们如何能够实践我们的说教,并把所有这些奇妙有用的内容,提供给我们渴望的读者。对于我来说,那就是文档的DevOps。

没错,就是DevOps。此术语自从诞生就论战不断,就我个人而言,我非常的讨厌论战,我作为scrum master(已退休)学会了很多,如何实现DevOps完全取决于你个人:拿到自己需要的,不要去担心你不会的,只要你的要点在正确的地方。

你个人的DevOps宣言

感谢灵活的DevOps的定义,有大量的方法来分解和组合这些实践,幸运的是,docsphere可提供更简化的故障,我们主要的输出是文章而不是代码。

再次,让我们来看下在这个领域里开源社区和红帽文档团队做什么。现在我们来尝试下分解文档的DevOps为以下几类:

●  统一的工具链

●  持续交付

●  合作

其中一些实践以及我即将列出的工具都是多年的经验累积,另外一些是围绕docsphere刚刚才获得的,让我兴奋的是,作者可以利用所有这些从工程师同行处获得的现有的知识,技能和工具,为我们的热心用户提供快捷和流畅的交付内容。

它同时也意味着我们可以为我们的内容做一些非常酷炫的事情!

●  统一的工具链

从源代码控制,标记语言,发布解析,到持续集成,自动化测试,从文字处理到印刷成书需要很长时间,还记得文档光盘吗?它并不完美。

开放源代码技术已经在推动这方面的努力中发挥了关键的作用。作为内容创作整体家族成员的创建文档需要快速、简明、和集成,且我们文档的代码使用的发布工具扮演了非常好的角色。

现在多数的核心文档都可以找到源文件,这些源文件使用一种或多种我们早已经掌握的标记语言,比如DocBook XML、Markdown (所有的 31种风格的 )、AsciiDoc和reStructuredText。这些文本文件通常使用git来做源代码控制(无论有没有github或gitlab的帮忙)。大多数的开源社区即使是红帽也使用git来管理他们的代码。

很多开源项目管理文档都接近于他们管理代码,或者干脆说和代码是一样的管理。其中一些成员热衷于基于项目构建来优化出版流程以及简化内容的贡献。举例来说,KDE社区使用一些灵巧的脚本来将Wiki转换为Docbook的指南,哪怕你是Markdown的忠实拥趸,照样可以使用强大的Docbook出版能力。NixOS使用Nix包管理器来给Nix文档打包。Github使用github来写github文档。 异常的强大!

在红帽以及其他大型的企业,众多产品的文档以及写作团队之间的缠斗意味着我们需要一些额外的制衡措施,以确保在所有的发展阶段,我们的文档是健全的。非常感谢,我们有激情四射的、非常有天份的同事,使用很多我们支持的开源的项目,不仅创造性地改进了我们的内部流程,还帮我们调整尽可能多的工具链。

下面是我们如何成为部署基于Jenkins持续集成的终极者的(我们也持续集成文档!)。每一个上游的提交不仅会检查整个产品文档库的诸如损坏的链接和一些错误,而且可生成HTML和PDF格式的文件,从而使我们可以在Jenkinscat用户界面中查看。基于Publican的解析器处理DockBook和AsciiDoc源文件到统一风格的所有输出,自动发布到用户门户,基于Gitlab的合并请求和内容审核。而且你完全拥有了属于自己的秘密武器(工具链)。

在自动化方面,关于API文档,对于JavaDoc,Sphinxauto-doc,以及AsciiDoctor等工具等的感谢是无须多讲的。近来,对于文档的单元测试也在风行一时,而不再仅限于代码了。崭露头角的工具如hemingway和emender等不是为你纠正语法错误的,而是会分析你的内容,并且会报告常见的语言错误,如复句,被动语态,动词的错误等。

希望我们将来会看到这些工具更多的贡献!比如它们可以自动完成一些比较繁琐的同行评审任务,比如可以帮助我们维护文档的一致性和简洁性。

●  持续交付

不同于它的工程部分,docsphere的实现更加注重内容的异步发布,它基本就意味着脱离软件交付,从而独立交付文档。

Freedom! 无论任何时候只要我们有需要就去自由的发布我们的文档,尽我们最大的努力去敏捷(有时,要比我们的工程师同事更加的多敏捷)。自由的去为产品提交补丁,还可以这么说,为原先发布的内容做进一步的完善。

那些开源项目的贡献者们也许会对我如此的激动窃笑不已,针对文档发布一个补丁和编辑wiki一样的简单,但是这在企业的世界里绝对是一个大的改变,当然,这是爱上开源公司的另外一个原因,来自社区的影响非常容易接受且非常的受欢迎。

在红帽,我们所有的文档都在红帽客户门户中作为官方产品发布来对外开放,这就意味着不论什么时候我们修改内容,我们都需要重新构建图书并上传,内容管理已经是我们工作中很自然的一部分了,当我们计划任务的时候,我们会尝试平衡未发布和已发布的内容创作。当一些人去抢着修复Heartbleed 或 Poodle-induced会应用到很多的产品以及图书时,此种做法就非常的方便。

我们是如何管理所有这些发布周期同步的了?它取决于具体的产品和团队。我们其中一个工程师团队使用类似敏捷的方法论,所以这样文档团队就相应和他们一起可以敏捷的迭代。其中还有文档团队独立于工程师团队来实施敏捷。其他一些团队甚至都不使用敏捷,而是选择早于发布周期开展内容的任务,以及当一个特性准备好可以写文档的时候才集中去写。

●  合作

“没有人能做到与世隔绝”,这是我经常重复的一个句子。这是有充分的原因的:没有合作,就不会有开放源代码项目。除了内容策略须做到以用户为中心之外,当我们创建文档时,我们必须听取相关合作者的声音。

那么,谁会是我们的合作对象呢?对于一个刚入门的人来说,每个人都是软件交付的参与者。开发者,测试工程师,产品经理,设计师,支持工程师,翻译者,哇塞,我们为了软件的发布交付而走在了一起,还有很多是作为一个产品的团队才合作的,或者说为了提供整个团队的沟通。还有,我们不应该忘记的有用户本身,(这才是意义本身)以及开源社区成员,企业级的客户,以及面对客户的工程师们。

多数的开源社区已经利用代码贡献的流程,不同深度的代码审核和社区治理,来应用于文档的实践。诸如Mozilla开发者文档项目展示了开源软件合作的原则以及内容社区的社区实现,以及OpenStack社区文档的重大启示:“文档应该和代码一样对待,都有社区驱动。”

对于开源社区项目的文档合作还有很长的一段路要走(正在进行),关于此方面将会在下一篇文章重点讨论!

在红帽文档战略现在能够占有一常驻席位,以及在所有的发布计划中拥有投票权,在产品管理会议中,能和在发布过程所有其他角色的代表待在一起。除了内部的地位稳固之外,我们也将我们对文档的反馈形成了一个闭环,无论是直接来自客户的反馈,还是来自技术客户经理,支持交付经理,和其他面对客户的团队的合作。

此种类型的合作对于我们来说是全新的,但是我非常的有信心,它会帮助我们优化我们的内容战略规划,当一旦和我们的持续交付原则所匹配时,将允许我们快速的交付内容给用户,那些用户到贡献者的用户进一步增强和修复我们的内容。

接下来做什么?

现在我们开始有了好几处的困惑;我们深信我们的经理或项目负责人能够认识到有价值的文档要好过于大而全的文档,而且我们尽可能的利用技术来实现平滑的内容交付,剩下的就是让人们去写一些内容,对不对?

好吧,还有一些依赖因素。当你的工作岗位里以这样或那样的方式包含有“作者”这个词汇时,那么就说的是你。但是你如何驾驭那些非常不稳定的开源贡献者呢?他们基本上是以志愿者的身份花时间为项目写代码的,而无需花时间,激励,相信他们的语言能力能写出你想要的所有这些文档?

下一篇文章里,我总结下围绕docsphere所做的努力,以及关于上述内容分享我自己的一些狂热想法。同时,我非常的渴望能够听到你们关于DevOps写作的实践的想法和故事。

二维码.gif

关注易云微信号,浏览更多技术文档

© 2011-2017 易云捷讯科技(北京)股份有限公司, 版权所有 | © 2011-2017 Eayun,Inc. All rights reserved.

京公网安备 11010802022475号 | 京ICP备 11028869号

业务咨询:400-606-6396