拯救你的文档 – 【DevOps敏捷开发动手实验】开源文档发布
今天上海的天气真是不错,风和日丽。再次来到微软上海紫竹研发中心,心情很是愉快,喜欢这里的大草坪,喜欢这里的工程气氛,更喜欢今天来陪我的小伙伴们。
这次动手实验培训与以往最大的不同就是采用了开源文档的方式。其实,小编一直在寻找一种更好的技术文档编写方式。说到文档,我在过去的几年中也写了不下500份不同类型的文档。我估计,每个写过技术文档的同学都有类似这样的文件夹。
是不是很有一种蛋疼的感觉,没有办法啊,需求改来改去,客户的要求变来变去 … … 最后么,就没有最后了,你就自己苦逼去吧。
所以,自从开始筹划这次培训开始,我就希望能够有一种更好的方式来编写技术文档,直到我发现了
这是微软下一代 ASP.NET的技术文档,但吸引我的是它右上角的这个 Edit on Github 链接,点进去一看果然发现它的源代码是在GitHub上开源的。
顺藤摸瓜,我找到了这个神奇的网站
研究一下,我发现使用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中建立了文档的主版本
– 在同事的github中fork我的主版本
– 可以同时编辑文档,并通过pull request互相分享最新的文档源码
– 在ReadTheDocs上建立了项目,同时设置了webhook,在向github push代码后直接部署到以下地址
这样,我们可以同时编写文档,就算同时修改了一个文件,也可以很容易的diff其中的区别,进行合并。同时,发布以后又可以很容易的分享给感兴趣的人。ReadTheDocs上面的文档是可以自动适应不同的设备的:
在PC浏览器中是
在手机浏览器中是这样的
在这次的培训中,学员也普遍反映这种文档非常好用,便于分享,还可以通过github的issue来反馈问题。
好吧,最后给出这次发布的VSALM-HOLs动手实验文档链接,感兴趣的同学可以通过以下链接访问,或者在github上fork我们的文档,如果遇到问题也欢迎通过github给我们提issue,甚至提交pull request,谢谢。
文档链接 (点击左下角 阅读原文 访问):
GitHub库地址:
请关注微信公众号 【devopshub】,获取更多关于DevOps研发运维一体化的信息