今天上海的天氣真是不錯，風和日麗。再次來到微軟上海紫竹研發中心，心情很是愉快，喜歡這裡的大草坪，喜歡這裡的工程氣氛，更喜歡今天來陪我的小夥伴們。
這次動手實驗培訓與以往最大的不同就是採用了開源文件的方式。其實，小編一直在尋找一種更好的技術文件編寫方式。說到文件，我在過去的幾年中也寫了不下500份不同型別的文件。我估計，每個寫過技術文件的同學都有類似這樣的資料夾。
是不是很有一種蛋疼的感覺，沒有辦法啊，需求改來改去，客戶的要求變來變去 … … 最後麼，就沒有最後了，你就自己苦逼去吧。
所以，自從開始籌劃這次培訓開始，我就希望能夠有一種更好的方式來編寫技術文件，直到我發現了
這是微軟下一代 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