DevOps文档中心的技术实践演进

这应该算是《Git企业开发者教程》的篇外篇,介绍一下这个教程是怎样写出来的。相信每个技术人都有类似下面的文件夹,保存着你辛苦工作的成果。实际的感觉:看着闹心,弃之不舍。一份文档久经修改,不能定稿,循环往复,结果就是一系列的v1 v2 v3 ……;这当然还是习惯比较好的技术人,习惯不好的,估计一个项目下来,各种文档存得哪里都有,最后自己都找不到了。

livedoc-2

既然要写git教程,当然不能用这种方式来写,不然我都好意思拿出来给大家看。

技术文档的编写其实和普通的文档编写有很大不同,因为里面的每个细节都很重要,最好能够像管理代码版本一样进行跟踪;对于项目/产品文档,你还可能会同时维护多个版本,这非常像我们日常的编码过程。这也是为什么很多技术人开始选择使用Markdown来编写文档。

DevOps 文档中心 v0.5

2016年3月的时候,我曾写过一篇 《拯救你的文档 – 【DevOps敏捷开发动手实验】开源文档发布》的博客,算是我对这种新的文档编写方式的第一次尝试,当时使用的是基于Phyton RestructureText和Readthedocs的引擎。这份文档至今仍然托管在github和readthedocs.org上面,算是对当时尝试的一种纪念

https://vsalm-hols.readthedocs.io/zh_CN/latest/

livedoc-13

当时的这个做法应该算是 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版本。

docs-ci-1

当时我写了另外一篇博客 《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 的工作方式如下图

2018-01-07_10-44-46

  • 核心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

2018-01-07_10-50-37

Git企业开发者教程
发布页:https://docs.devopshub.cn/mdwiki/#!docs/g4e/index.md
Github库:https://github.com/lean-soft/devopshub-docs-g4e

2018-01-07_10-52-31

2018-01-07_10-52-48

以上便是 DevOps 文档中心在过去一年中的演变,当然现在的实现仍然存在问题,比如:文档中心的导航仍然需要收工维护,这个问题我们打算使用构建中自动扫描文档标题的方式来解决。

我们是中国最好的DevOps实施团队,我们不仅会讲DevOps,我们更能做DevOps,持续改进中。


 

相关文章:


请关注微信公众号 【devopshub】,获取更多关于DevOps研发运维一体化的信息

qrcode_for_gh_b7c158df1fd1_430