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

本文来自互联网用户投稿,该文观点仅代表作者本人,不代表本站立场。本站仅提供信息存储空间服务,不拥有所有权,不承担相关法律责任。如若转载,请注明出处:http://www.mzph.cn/news/322372.shtml

如若内容造成侵权/违法违规/事实不符,请联系多彩编程网进行投诉反馈email:809451989@qq.com,一经查实,立即删除!

相关文章

CF7D-Palindrome Degree【字符串hash,dp】

正题 luogu链接:https://www.luogu.org/problemnew/show/CF7D 题目大意 定义kkk级回文串为一个字符串的(1,⌊n/2⌋)(1,\lfloor n/2 \rfloor)(1,⌊n/2⌋)和(n−⌊n/2⌋,n)(n-\lfloor n/2 \rfloor,n)(n−⌊n/2⌋,n)都是k−1k-1k−1级回文串。 求这个字符的所有前缀的回文串等级…

MySQL UPDATE 语句一个“经典”的坑

转载自 MySQL UPDATE 语句一个“经典”的坑 来源:ju.outofmemory.cn/entry/336774 有问题的SQL语句 why? 倒回去再重试验一把 最近好几次有开发同学在钉钉上问我,比如下图: 问题归纳起来就是:在MySQL里面update一条记录&…

jzoj4803-[NOIP2016提高A组模拟9.28]求导【模拟】

正题 题目大意 求一个标准多项式的求导 解题思路 暴力模拟即可,注意细节即可 一下是贴心的坑爹细节样例 (233x)−>(1)而不是(1)(233x)->(1)而不是(1)(233x)−>(1)而不是(1) (1)−>(0)而不是()(1)->(0)而不是()(1)−>(0)而不是() codecodecode …

g4e基础篇#1 为什么要使用版本控制系统

本篇是Git企业开发者教程基础篇的第一篇1. 基础篇:为什么要使用版本控制系统Git 分布式版本控制系统的优势Git 安装和设置初始化Git存储库(Repo)起步 1 – 创建分支和保存代码起步 2 – 了解Git历史记录起步 3 – 拉取请求 Pull Request 工作机制Git是一种版本控制系…

15-多对多做左连接查询(查询老师,并且把关联的学生也查出来)

多对多左连接查询 目录 左连接查询老师对学生是多对多的关系,把中心放在老师上,一个老师可以教多个学生,实际上老师对学生也可以理解为一对多的关系。 左连接查询 场景:查询老师,并且把关联的学生也查出来。 Teac…

2.数据湖DeltaLake之DDL操作

转载自 2.数据湖DeltaLake之DDL操作 前面讲了delta lake简介,特性及基本操作。本文主要是讲DeltaLake的DDL操作,实际上是依赖于spark datasourcev2 和catalog API(3.0)的,所以Deltalake整合spark的时候最好是3.0开始…

jzoj4804-[NOIP2016提高A组模拟9.28]成绩调研【指针,模拟】

正题 题目大意 求一个序列里有多少个区间满足kkk的个数在lr∼rkl_r\sim r_klr​∼rk​之间 解题思路 首先十分显然对于一个固定的右端点rrr可以匹配的左指针一定是一个区间[L2..L1−1][L_2..L_1-1][L2​..L1​−1]。 也就是[L2..L1−1][L_2..L_1-1][L2​..L1​−1]任意一个作…

.Net 如何模拟会话级别的信号量,对http接口调用频率进行限制(有demo)

现在,因为种种因素,你必须对一个请求或者方法进行频率上的访问限制。 比如, 你对外提供了一个API接口,注册用户每秒钟最多可以调用100次,非注册用户每秒钟最多可以调用10次。比如, 有一个非常吃服务器资源的…

(八)IT_开发常用单词大全

开发单词 单词 音标 注释 a collection of… 一组… a couple of… 几个 a kind of 一种 a number of… 许多… a point in time n.时间点 a set of… 一组… a series of 一系列 ability [əbɪlətɪ] n.能力 absence [ˈbsəns] …

1.数据湖deltalake初识

转载自 1.数据湖deltalake初识 1.delta特性简介 Delta Lake是Spark计算框架和存储系统之间带有Schema信息数据的存储中间层。它给Spark带来了三个最主要的功能: 第一,Delta Lake使得Spark能支持数据更新和删除功能; 第二,Del…

Quartz.NET 3.0 正式发布

Quartz.NET是一个强大、开源、轻量的作业调度框架,你能够用它来为执行一个作业而创建简单的或复杂的作业调度。它有很多特征,如:数据库支持,集群,插件,支持cron-like表达式等等。在2017年的最后一天Quartz.…

jzoj4805-[NOIP2016提高A组模拟9.28]跟踪【dfs,树】

正题 题目大意 一棵树一个人从sss开始,有两个追击者从p,qp,qp,q出发, 在3k1s3k1\ s3k1 s,那个人走 在3k2和3k3s3k2和3k3\ s3k2和3k3 s,追击者走。 求那个人最久多久不会被追上。 解题思路 首先计算出每个点距离两个追击者和那个…

ScheduledThreadPool中的Leader-Follow模式你知道不?

转载自 ScheduledThreadPool中的Leader-Follow模式你知道不? ScheduledThreadPoolExecutor 是java中一个非常常用的定时调度的工具,其提供了两种定时调度常用模式: 1.固定调度周期的任务执行。 2.固定延迟间隔的任务执行,延迟间隔表示的是…

(九)IDEA便捷配置MyBatis.xml文件

在使用IDEA新建mybatis.xml经常需要手动复制粘贴之前的xml配置。这样也比较麻烦。我们可以IDEA进行关于xml的配置 1.创建MyBatis Config的模版 1.打开新增2.查看编辑页面查看编辑页面 我们看到Name:为我们新增模版的文件名称。Extension:为我们新增文件…

用 Identity Server 4 (JWKS 端点和 RS256 算法) 来保护 Python web api

目前正在使用asp.net core 2.0 (主要是web api)做一个项目, 其中一部分功能需要使用js客户端调用python的pandas, 所以需要建立一个python 的 rest api, 我暂时选用了hug, 官网在这: http://www.hug.rest/.目前项目使用的是identity server 4, 还有一些web api和js client.项目…

欢乐纪中A组莫名其妙赛【2019.6.6】

前言 好像明天他们就高考了,先祝福一波。 然后今天AKKKKKKKKKKKKKKKKKKKKKKKKK!AKKKKKKKKKKKKKKKKKKKKKKKKK!AKKKKKKKKKKKKKKKKKKKKKKKKK! 成绩 JJJ表示初中,HHH表示高中后面加的是几年级 RankRankRankPersonPersonPersonScoreScoreScoreAAABBBCCC111(…

MySQL死锁如何处理

转载自 MySQL死锁如何处理 前提 笔者负责的一个系统最近有新功能上线后突然在预警模块不定时报出MySQL死锁导致事务回滚。幸亏,上游系统采用了异步推送和同步查询结合的方式,感知到推送失败及时进行了补偿。于是,笔者争取了一点时间详细分析…

(十)IDEA添加mybatis-mapp.xml文件

1.点击file–Settings–Editor–file and Code Templates 2.配置mybatis-mapper.xml的网址,点击file–Settings–ages& Frameworks–Schmas and DTDs 3.创建mapper.xml文件

g4e基础篇#2 Git分布式版本控制系统的优势

1. 基础篇:为什么要使用版本控制系统Git 分布式版本控制系统的优势Git 安装和设置初始化Git存储库(Repo)起步 1 – 创建分支和保存代码起步 2 – 了解Git历史记录起步 3 – 拉取请求 Pull Request 工作机制Git是当前最棒的版本控制系统,已经迅速成为了事…

P4989-二进制之谜【堆,贪心】

正题 题目链接:https://www.luogu.org/problemnew/show/P4989 题目大意 一个二进制数两两配对,要求 配对的数不能交叉(用同一个区间但不包含)0在前1在后 要求配对最多的情况下所有配对的距离之和最远。 解题思路 将0视为左括号,1视为右括号&#xf…