拯救你的文檔 – 【DevOps敏捷開發動手實驗】開源文檔發佈

今天上海的天氣真是不錯，風和日麗。再次來到微軟上海紫竹研發中心，心情非常愉快，喜歡這裏的大草坪，喜歡這裏的工程氣氛，更喜歡今天來陪個人小夥伴們。

此次動手實驗培訓與以往最大的不一樣就是採用了開源文檔的方式。其實，小編一直在尋找一種更好的技術文檔編寫方式。說到文檔，我在過去的幾年中也寫了不下500份不一樣類型的文檔。我估計，每一個寫過技術文檔的同窗都有相似這樣的文件夾。

是否是頗有一種蛋疼的感受，沒有辦法啊，需求改來改去，客戶的要求變來變去 … … 最後麼，就沒有最後了，你就本身苦逼去吧。

因此，自從開始籌劃此次培訓開始，我就但願可以有一種更好的方式來編寫技術文檔，直到我發現了

http://docs.asp.net

這是微軟下一代 ASP.NET的技術文檔，但吸引個人是它右上角的這個 Edit on Github 連接，點進去一看果真發現它的源代碼是在GitHub上開源的。

順藤摸瓜，我找到了這個神奇的網站 https://readthedocs.org/

研究一下，我發現使用GitHub + ReadTheDocs.org，終於能夠知足我對技術文檔的編寫要求了：

– 你所編寫的內容是與展示形式無關的：這裏使用的格式是reStructuredText，這是一種相似Markdown的標記語言，好比：

文檔源代碼

生成的HTML效果

是否是很cool，特別是最下面的 練習列表 部分，只要直接引用相關的文件，就能夠生成很漂亮的連接。

– 文檔的源碼仍然具有很好的可讀性：相比HTML而言，reST格式的各類標記與內容融合在一塊兒的，而不是環繞在你的源碼周圍的，比較一下表格的寫法，你就知道我是什麼意思了。

源碼

生成的HTML效果

想象一下若是要編寫這樣的表格，用HTML代碼如何寫你就知道個人意思了。

– 文檔能夠以多種格式輸出：reST能夠被很容易的解析成HTML，PDF，ePub等多種發佈格式，便於在不一樣的設備上進行訪問，注意左側的Downloads部分

– 能夠很容易的比較和跟蹤內容變動：相似word/html這種文檔，是很難進行版本比較的，但reST讓着一切變得無比容易，並且你可使用很簡單的純文本編輯器，不在須要笨重的Word。

使用Visual Studio Code進行內容比較

– 能夠藉助git豐富的分佈式協做來支持多人同時編輯，離線編輯，多分支，合併等複雜的協做場景。

此次的培訓中所使用的文檔編寫流程：

– 在個人github中創建了文檔的主版本
https://github.com/ups216/vsalm-hols
– 在同事的github中fork個人主版本
– 能夠同時編輯文檔，並經過pull request互相分享最新的文檔源碼
– 在ReadTheDocs上創建了項目，同時設置了webhook，在向github push代碼後直接部署到如下地址
https://vsalm-hols.readthedocs.org/

這樣，咱們能夠同時編寫文檔，就算同時修改了一個文件，也能夠很容易的diff其中的區別，進行合併。同時，發佈之後又能夠很容易的分享給感興趣的人。ReadTheDocs上面的文檔是能夠自動適應不一樣的設備的：

在PC瀏覽器中是

在手機瀏覽器中是這樣的

在此次的培訓中，學員也廣泛反映這種文檔很是好用，便於分享，還能夠經過github的issue來反饋問題。

好吧，最後給出此次發佈的VSALM-HOLs動手實驗文檔連接，感興趣的同窗能夠經過如下連接訪問，或者在github上fork咱們的文檔，若是遇到問題也歡迎經過github給咱們提issue，甚至提交pull request，謝謝。

文檔連接：
https://vsalm-hols.readthedocs.org

GitHub庫地址：
https://github.com/ups216/vsalm-hols