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

Posted 2021-04-16 DevOps

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

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

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

DevOps 文档中心 v0.5

2016年3月的时候，我曾写过一篇 的博客，算是我对这种新的文档编写方式的第一次尝试，当时使用的是基于Phyton RestructureText和Readthedocs的引擎。这份文档至今仍然托管在github和readthedocs.org上面，算是对当时尝试的一种纪念

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

当时我写了另外一篇博客介绍了我们的一些做法，包括使用 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，持续改进中。

---

 相关文章：

• 
  

•