β

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

DevOps 门户 72 阅读

这应该算是 《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

上面的做法基本上满足我们日常技术文档编写,维护,多版本发布需求,但是也存在一些问题,比如:

基于以上这些诉求,我们开始规划 v2.0。最后我们决定采用MDWIKI来直接通过js转换md为html,这样就避免了在构建的时候进行文档格式转换,可以与大家在github上发布文档的方式高度统一;同时因为全部前端技术实现,定制也更加容易。大型Git库的问题我们暂时采用git submodule的方式来将多个库进行整合,这样可以避免使用多条TFS发布流水线。这个过程要特别感谢我同事厉小明,在其中做了大量工作。

当前的 DevOps 文档中心 v2.0 的工作方式如下图

2018-01-07_10-44-46

大家看到的效果就是这样

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

作者:DevOps 门户
关于研发运维一体化(DevOps)的一切
原文地址:DevOps文档中心的技术实践演进, 感谢原作者分享。

发表评论