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文档中心的技术实践演进的全部內容，希望文章能夠幫你解決所遇到的問題。
- 上一篇： 利用Service Fabric承载eS
- 下一篇： g4e基础篇#3 Git安装与配置