拯救你的文档 – 【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