DevOps文档中心的技术实践演进
这应该算是《Git企业开发者教程》的篇外篇,介绍一下这个教程是怎样写出来的。相信每个技术人都有类似下面的文件夹,保存着你辛苦工作的成果。实际的感觉:看着闹心,弃之不舍。一份文档久经修改,不能定稿,循环往复,结果就是一系列的v1 v2 v3 ……;这当然还是习惯比较好的技术人,习惯不好的,估计一个项目下来,各种文档存得哪里都有,最后自己都找不到了。
既然要写git教程,当然不能用这种方式来写,不然我都好意思拿出来给大家看。
技术文档的编写其实和普通的文档编写有很大不同,因为里面的每个细节都很重要,最好能够像管理代码版本一样进行跟踪;对于项目/产品文档,你还可能会同时维护多个版本,这非常像我们日常的编码过程。这也是为什么很多技术人开始选择使用Markdown来编写文档。
DevOps 文档中心 v0.5
2016年3月的时候,我曾写过一篇 《拯救你的文档 – 【DevOps敏捷开发动手实验】开源文档发布》的博客,算是我对这种新的文档编写方式的第一次尝试,当时使用的是基于Phyton RestructureText和Readthedocs的引擎。这份文档至今仍然托管在github和readthedocs.org上面,算是对当时尝试的一种纪念
https://vsalm-hols.readthedocs.io/zh_CN/latest/
当时的这个做法应该算是 DevOps 文档中心 的雏形,v0.5版本。后来我的团队在2016-2017年间的客户项目实施,公开课培训和企业内容过程中先后编写了一共超过20套培训文档,分布在超过40个Git存储库中,以下只是列出一些比较成体系的并还存在于最新版文档中心内的
– 微软云端开发训练营
– 基于Docker的DevOps实战培训(微软研发云版)
– 基于Docker的DevOps实战培训(开源工具版 GitLab + Jenkins + ELK)
– Docker 实战
– Apache Mesos 实战
– Jenkins 实战
DevOps 文档中心 v1.0
这些文档后来被我们整合成了 DevOps 文档中心,基本上就是用了一个索引页将所有的文档入口连接到一起。就成了下面这个样子;这算是文档中心第一次成型,v1.0版本。
当时我写了另外一篇博客 《Markdown/reST 文档发布流水线》介绍了我们的一些做法,包括使用 docker 进行 rst 文档的生成并使用 Visual Studio Team Services 发布流水线进行自动化发布。
同时,我们也开始借助这些文档配合我们的 DevOps 实验室 提供线上/线下的实战培训,取得了非常好的效果,关于 DevOps 实验室 随后我会单独写一篇博客介绍它的技术架构和我们的DevOps实践。
DevOps 文档中心 v2.0
上面的做法基本上满足我们日常技术文档编写,维护,多版本发布需求,但是也存在一些问题,比如:
文档格式使用的是RestructuredText:我相信很多人都没有听过这个格式,这个格式是Python中用于编写文档的格式,语法和Mardown非常接近。2017年我们 LEANSOFT 团队加入了很多新人,大家都对单独学习一种新的语法有抵触。我自己也不希望我们采用和社区不同的标准,这样会让未来的维护成本越来越大。
文档库规模越来越大:我粗略统计了一下,截止2017年12月,我们大概编写了超过2000页的rst文件,总代码行数超过200,000行,其中还包括大量的图片资料。这些内容都散布在超过40个git存储库中,总数据量超过2个G。这40多个Git存储库每个后面都连接了一个TFS的发布流水线。这让管理起来成本很高,经常会有同事来问我应该哪个个库,而我自己也很难搞清楚了。
定制困难:在v1.0的过程中,我们虽然剥离了Readthedocs的引擎,仅仅保留sphinx工具来转换rst到html,简化了我们的TFS发布流水线,但是这个引擎很难定制。特别是我不希望团队还需要学习python才能完成定制。我们希望后续在文档中心中提供诸如:
DevOps 实验室集成:在相关文档上直接一键创建对应试验环境并开始试验。
留言/讨论:允许用户留言并针对内容进行讨论
基于以上这些诉求,我们开始规划 v2.0。最后我们决定采用MDWIKI来直接通过js转换md为html,这样就避免了在构建的时候进行文档格式转换,可以与大家在github上发布文档的方式高度统一;同时因为全部前端技术实现,定制也更加容易。大型Git库的问题我们暂时采用git submodule的方式来将多个库进行整合,这样可以避免使用多条TFS发布流水线。这个过程要特别感谢我同事厉晓明,在其中做了大量工作。
当前的 DevOps 文档中心 v2.0 的工作方式如下图
核心git repo现在只有两个: home和mdwiki,分别承载首页和mdwiki的解析工作
所有的文档都在独立的repo之内,通过git submodule的方式即成到mdwiki的存储库,这个做法解决了2个问题
大家通过submodule的引用关系就知道了文档结构并能找到对应的git仓库
主库大小得到控制,数据仍然存放在子库,只是在构建发布的时候才集成进来
主站点TFS发布流水线负责将home/mdwiki发布到Azure的App Service中的不同应用
Github的TFS发布流水线负责将分库的内容双向到Github上的lean-soft账号下面,使用双向同步是为了能够从社区接受pull request,为未来添加留言和评论留出实现的地方。
大家看到的效果就是这样
DevOps文档中心首页:https://docs.devopshub.cn/home
(点击阅读原文即可访问)
Git企业开发者教程
发布页:https://docs.devopshub.cn/mdwiki/#!docs/g4e/index.md
Github库:https://github.com/lean-soft/devopshub-docs-g4e
以上便是 DevOps 文档中心在过去一年中的演变,当然现在的实现仍然存在问题,比如:文档中心的导航仍然需要收工维护,这个问题我们打算使用构建中自动扫描文档标题的方式来解决。
我们是中国最好的DevOps实施团队,我们不仅会讲DevOps,我们更能做DevOps,持续改进中。
原文地址:http://devopshub.cn/2018/01/07/devops-docs-practise/
.NET社区新闻,深度好文,欢迎访问公众号文章汇总 http://www.csharpkit.com
DevOps文档中心的技术实践演进相关推荐
- AI × OCR:腾讯文档表格图像识别技术实践
本文主要介绍基于深度神经网络的表格图像识别解决方案. 作者:腾讯QQ研发中心--CV应用研究组的yonke 1.前言 1.1背景 大多数人日常办公处理的文件,无非就是表格和文档,其中表格的重要性毋庸置 ...
- 微服务实践分享(9)文档中心
1.文档中心 在项目中,需要协同开发,所以会写许多API文档给其他同事,以前都是写一个简单的TXT文本或Word文档,口口相传,这种方式比较老土了,所以,需要有个api管理系统专门来管理这些api 2 ...
- 在线文档有哪些技术难点
实现一个多人协作在线文档有哪些技术难点? 想知道实现类似于语雀.石墨文档或腾讯文档等产品的难点在哪些地方? 大体上说,多人协作的在线文档在技术上主要分成三大块:"在线"." ...
- Java支持latex,基于Java和LaTeX的文档自动生成技术研究
基于Java和 LaTeX 的文档 自动生成技术研究 ◆尚宝欣 徐 屹 (东北电力大学理学院,吉林 长春 132012) [摘 要]讨论了结合Java与LaTex 自动生成 PDF文档的方法.针 展名 ...
- 项目视频讲解_深入浅出Lucene4.X实战开发大型企业文档中心管理系统
深入浅出Lucene4.X实战开发大型企业文档中心管理系统 视频教程:http://pan.baidu.com/s/1CcuVM
- 年度盘点丨产品在线帮助文档/中心怎么做?看完这4个案例就知道
盘点之前先来聊下在线帮助文档/中心的作用 在线的帮助文档/中心就是将纸质版的产品操作说明迁移到互联网上的一种呈现方式.其作用是为了帮助用户加深产品认知,减少操作难度.如今线上营销火热的环境下,在线帮助 ...
- (十一)Alian 的 Spring Cloud 文档中心(swagger聚合文档)
目录 一.简介 1.1.maven依赖 二.核心配置类 2.1.SwaggerUI配置 2.2.服务定义的上下文 2.3.定时刷下文档定义 2.4.文档接口 三.配置 3.1.主类 3.2.boots ...
- VuePress 手摸手教你搭建一个类Vue文档风格的技术文档/博客
前言: VuePress是尤大为了支持 Vue 及其子项目的文档需求而写的一个项目,VuePress界面十分简洁,并且非常容易上手,一个小时就可以将项目架构搭好.现在已经有很多这种类型的文档,如果你有 ...
- java怎样生成文档_java中如何创建文档中心的目录
public static void createDocDir() throws UnsupportedEncodingException, DocumentException, Exception{ ...
最新文章
- mysql大表join小表速度很慢_mysql多表join中,为什么子查询会那么慢,怎么解决-问答-阿里云开发者社区-阿里云...
- 客户端登录提示找不到表0
- 【hortonworks/registries】Parameter Schema name is null
- Ubuntu下使用Git_2
- mysql 5.7.13 log_有关binlog的那点事(二)(mysql5.7.13)
- 从Python迁移到Go的原因和好处
- 分布式 id 生成系统 滴滴 Tinyid 快速入门
- 计算机专业 英语词汇大全(持续更新)
- 如何进入百度、阿里,一个6年Android老司机的面经
- wmware虚拟网卡 VMnet8 VMnet1未识别网络解决方法
- 【云原生之Docker实战】使用Docker部署NodeBB社区平台
- photos怎么改成中文_picsart怎么设置中文?picsart怎么改成中文字体教程
- 起点web端体验报告
- Error waiting for a debug connection: Bad state: No element
- ABC243 ABCDE
- 倍福PLC--实现Dword数据类型每位1的计数,即统计类型中“1”的位数
- Canon单反相机的镜头校正方法
- 项目计划太复杂?试试思维导图
- 《电路基础》戴维南定理
- 12.深入浅出:交流负反馈对放大电路性能的影响——参考《模拟电子技术基础》清华大学华成英主讲