为什么引入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
为什么引入devops_DevOps可以为您的文档做什么?相关推荐
- 揭秘新推广渠道::利用腾讯文档做QQ消息弹窗
圈内营销大佬推广又搞出了新路子,利用腾讯文档做QQ微信消息弹窗推广,折腾出了一种新的推广方式! 在之前,很多站长估计之前都没有仔细观察注腾讯文档这个产品,都是用来在线编辑文档办公用,很多人没想到是,最 ...
- Vue 引入Ueditor修改样式仿照Word文档
前言 项目中有涉及到对文本生成和文本内容编辑的需求,选择了百度的Ueditor.项目使用Vue框架.便于利用双向数据绑定特性,完成文本的生成. 效果图 Vue 引入Ueditor 下载Ueditor ...
- visio的字体复制到word_学会这6个常用Word技巧,文档做起来又快又好看,办公如有神助...
Word.Excel.PPT作为office家三兄弟,哪个你最熟悉?很多小伙伴都选择了Word,毕竟平常写报告.写论文,和它接触最多了~ 然而,它就像你身边最熟悉的陌生人,看着熟悉,一问三不知,不信? ...
- navicat 复制表结构到word文档做数据库设计格式问题解决
需求:写数据库设计文档,需要设计数据字典,贴表结构,如果是几百张表 一个个填工作量很大 解决方案: 1.sql查询所有字段 2.整体复制到excel 3.拆分表,调整列项及字段自动编号 4.复制到wo ...
- erp服务器配置文档,做erp用什么服务器配置
做erp用什么服务器配置 内容精选 换一换 为弹性云服务器配置的安全组规则未生效.以下排查思路根据原因的出现概率进行排序,建议您从高频率原因往低频率原因排查,从而帮助您快速找到问题的原因.如果解决完某 ...
- 引入swagger2 api接口文档并实现离线文档
文章目录 前言 目的 导入工具 写一个config类 启动类添加注解 试启动页面 补充并实现文档 特殊点 再次启动页面 导出swagger在线文档为离线文档 忽略SSL证书 前言 本篇文章在于介绍sw ...
- BOM 浏览器对象模型和DOM 文档对象模型
浏览器对象模型BOM 1. 浏览器对象模型介绍 BOM(Browser Object Model) 是指浏览器对象模型,是用于描述这种对象与对象之间层次关系的模型,浏览器对象模型提供了独立于内容的.可 ...
- 微软语音AI技术与微软听听文档小程序实践 | AI ProCon 2019
演讲嘉宾 | 赵晟.张鹏 整理 | 伍杏玲 来源 | CSDN(ID:CSDNnews) [导语]9 月 7 日,在CSDN主办的「AI ProCon 2019」上,微软(亚洲)互联网工程院人工智能语 ...
- C#解析Markdown文档,实现替换图片链接操作
前言 又是好久没写博客了 其实也不是没写,是最近在「做一个博客」,从2月21日开始,大概一个多星期的时间,疯狂刷进度,边写代码边写了一整系列的博客开发笔记,目前为止已经写了16篇了,然后上3月之后工作 ...
最新文章
- 【bzoj3261】最大异或和 可持久化Trie树
- iOS cell 里需要创建n个元素
- 清单革命:为什么不仅是工具革命
- php printf 0.2f,php printf()
- linux top 中的内存 与 free,linux top命令下内存资源的讨论,高手请进。。。
- TensorFlow VGG16
- 单例模式-Java实现-非延迟加载、延迟加载
- android课程设计时钟,单片机制作的电子钟(含闹钟功能)课程设计报告
- eclipse中文汉化操作 2020-12
- unity物理引擎详解
- 台式计算机cpu允许温度,台式机cpu温度多少正常 台式机cpu正常温度
- Py之lime:lime库的简介、安装、使用方法之详细攻略
- 1077E Thematic Contests 【二分答案】
- 基于深度学习的自动车牌识别(详细步骤+源码)
- 纯净Vue模板安装教程
- java项目-第34期基于SpringBoot实现的中小医院HIS管理系统【毕业设计】
- java多线程,卖票案例
- linux聚合网卡--解除聚合网卡(2)
- git笔记(本地操作教程)
- island of java_专业英语试卷
热门文章
- MyBatis Generator(MBG)从Abator迁移
- 如何迅速掌握并提高linux运维技能
- 基于.NET的分词软件设计与实现V1.0--总体思路及算法实现
- 有用的收藏!javascript/c#/asp.net
- idea导入项目无法通过tomcat插件无法运行记录
- GTN-Graph Transformer Network 图变换网络 NeurIPS2019
- js视频html代码,html+JS刷图实现视频效果(示例代码)
- 电子商务c语言实训报告,中南民族大学电子商务C语言实验报告.doc
- Ubuntu18.04创建新的系统用户
- 在eclipse中安装jadclipse的反编译插件