@xishuixixia
2015-09-28T04:05:50.000000Z
字数 3599
阅读 2107
开源 文档
在上一篇：《内容为王，技术文档新理念》中我们围绕技术文档探讨了理念的转变，以及新的、令人振奋的针对用户关心的方法。
我们已经拥有了关于who、what、when、where，以及why的伟大的启示，接下来，我们将要介绍如何才能撰写好的文档。对于我来说，那就是文档的DevOps。
没错，就是DevOps。此术语自从诞生就论战不断，就我个人而言，我非常的喜欢论战，我作为scrum master（已退休）学会了很多，如何实现DevOps完全取决于你个人：拿到自己需要的，不要去担心你不会的，直到一切都回到自身的位置。
感谢灵活的DevOps的定义，有大量的方法来分解和组合这些实践，幸运的是，docsphere经受的起多处的分解，我们主要的目的是文章而不是代码。
再次，让我们来看下在这个领域里开源社区和红帽文档团队做什么。现在我们来尝试下分解文档的DevOps为以下几类：
其中一些实践以及我即将列出的工具都是多年积累下来的，另外一些是围绕docsphere不久前才学习到的，让我兴奋的是，作者可以利用所有这些现有的知识，技能和工具，与我们的工程师并行共创快捷和流畅，然后将内容交付我们热心的用户。
它同时也意味着为我们的内容做一些非常酷炫的事情！
从源代码控制，标记语言，发布解析，到持续集成，自动化测试，以及从文字处理到印刷成书之间漫长的等待，还记得文档持续交付吗？它并不完美。
开放源代码技术已经在推动这方面的努力中发挥了关键作用。作为内容创作整体家族成员的创建文档，它需要快速、简明和集成，且我们文档代码使用的发布工具扮演了非常重要的角色。
现在多数的核心文档都可以找到源代码文件，这些源代码文件使用一种或多种我们早已经掌握的标记语言，比如DocBook XML、Markdown、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、Sphinx auto-doc，以及AsciiDoctor等工具等感谢是无须多讲的。近来，对于文档的单元测试也在风行一时，而不再仅限于代码了。崭露头角的工具如[hemingway]http://www.hemingwayapp.com/和emender等不是为你纠正语法错误的，而是分析你的内容，并且会报告常见的语法错误，如复句、被动语态、动词的错误等。
希望我们将来会看到更多的对于这些工具的贡献！比如它们可以自动完成一些比较繁琐的同行评审任务，比如可以帮助我们维护文档的一致性和简单性。
不同于它的工程部分，docsphere的实现更加注重内容的异步发布，它就意味着脱离软件交付，从而交付文档成为一个独立的流程。
Freedom！ 无论任何时候只要我们有需要就去自由的发布我们的文档，尽我们最大的努力去敏捷，自由度更高的敏捷（有时，要比我们的工程师同事更加的敏捷）。自由的去为产品提交补丁，还可以这么说，为原先发布的内容做进一步的完善。
那些开源项目的贡献者们也许会对我如此的激动窃笑不已，针对文档发布一个补丁和编辑wiki一样的简单，但是这在企业的世界里绝对是一个大的改变，当然，这是爱上开源公司的另外一个原因，来自社区的影响非常容易接受且非常的受欢迎。
在红帽，我们所有的文档都在红帽客户门户中作为官方产品发布的对外开放，这就意味着不论什么时候我们修改内容，我们都需要重新构建图书并上传，内容的变化已经是我们工作中很自然大一部分了，当我们计划任务的时候，我们会尝试平衡发布和已发布的内容。当一些人去抢着修复Heartbleed 或 Poodle－induced会应用到很多的产品以及图书时，此种做法就非常的方便。
我们是如何管理所有这些发布周期同步的了？它取决于具体的产品和团队。我们其中一个工程师团队使用类似敏捷的方法论，所以这样文档团队就相应和他们一起可以敏捷的迭代。其中还有文档团队独立于工程师团队来实施敏捷。其他一些团队甚至都不使用敏捷，而是选择早于发布周期开展内容的任务，当一个特性准备好可以写文档的时候才集中去写。
"没有人能做到与世隔绝"，这是我经常重复的一个句子。这是有充分的理由的：没有合作，就不会有开放源代码项目。除了内容策略须做到以用户为中心之外，当我们创建文档时，我们必须听取相关合作者的声音。
那么，谁会是我们的合作对象了呢？对于一个刚入门的人来说，每个人都是软件交付的参与者。开发者、测试工程师、产品经理、设计师、支持工程师、翻译者，哇塞，我们为了软件的发布交付而走在了一起，还有很多是作为一个产品的团队才合作的，或者说为了提供整个团队的沟通。还有，我们不应该忘记的有用户本身，（这才是意义本身）以及开源社区成员，企业级的客户，以及面对客户的工程师们。
多数的开源社区已经把代码贡献的流程，不同深度的代码审核和社区治理，应用于文档管理中。诸如Mozilla开发者文档项目展示了开源软件合作的原则以及内容社区的社区实现，以及OpenStack社区文档的重大启示：“文档应该和代码一样对待，都由社区驱动。”
对于开源社区项目的文档合作还有很长的一段路要走（正在进行），关于此方面将会在下一篇文章重点讨论！
在红帽，文档战略现在能够占有一常驻席位；在所有的发布计划中拥有投票权；在产品管理会议中，能够和在发布过程所有其他角色的代表一起共同决策。除了内部的地位稳固之外，我们也将我们对文档的反馈形成了一个闭环，无论是直接来自客户的反馈，还是来自技术客户经理，支持交付经理，和其他面对客户的团队。
此种类型的合作对于我们来说是全新的，但是我非常的有信心，它会帮助我们优化我们的内容战略规划，一旦和我们的持续交付原则所匹配时，将允许我们快速的交付内容给用户，这样可进一步的发展用户成为贡献者，从而进一步增强和修复我们的内容。
现在我们开始有了好几处的困惑：我们深信我们的经理或项目负责人能够认识到有价值的文档要好过于大而全的文档，而且我们尽可能的利用技术来实现平滑的内容交付，剩下的就是让人们去写一些内容，对不对？
好吧，还有一些依赖因素。当你的工作岗位里以这样或那样的方式包含有“作者”这个词汇时，那么就说的是你。但是你如何驾驭哪些非常不稳定的开源贡献者了呢？他们基本上是以志愿者的身份花时间为项目写代码的，而无需花时间，激励，相信他们的语言能力能写出你想要的所有这些文档？
下一篇文章里，我总结下围绕docsphere以及关于上述内容分享我自己的“狂热之旅”。同时，我非常的渴望能够听到读者－你的关于DevOps写作的实践的想法和故事。
htcvwi8z.jpg?itok=f7t4N_Jf未知大小Mikey Ariel， 著名开源项目oVirt社区负责人，目前是红帽的OpenStack平台的高级技术作者，工作地点在Brno，CZ，空闲时间，她是欧洲文档写作的领导者，Django girl的聚会组织者，开源项目的文档教练，在开源会议上是热情的演讲者，会谈及关于文档，敏捷和社区。请关注她的twitter：thatdocslady