拯救你的文档 – 【DevOps敏捷开发动手实验】开源文档发布

时间:2023-06-26 16:03:32

今天上海的天气真是不错,风和日丽。再次来到微软上海紫竹研发中心,心情很是愉快,喜欢这里的大草坪,喜欢这里的工程气氛,更喜欢今天来陪我的小伙伴们。

拯救你的文档 – 【DevOps敏捷开发动手实验】开源文档发布

这次动手实验培训与以往最大的不同就是采用了开源文档的方式。其实,小编一直在寻找一种更好的技术文档编写方式。说到文档,我在过去的几年中也写了不下500份不同类型的文档。我估计,每个写过技术文档的同学都有类似这样的文件夹。

拯救你的文档 – 【DevOps敏捷开发动手实验】开源文档发布

是不是很有一种蛋疼的感觉,没有办法啊,需求改来改去,客户的要求变来变去 … … 最后么,就没有最后了,你就自己苦逼去吧。

所以,自从开始筹划这次培训开始,我就希望能够有一种更好的方式来编写技术文档,直到我发现了

http://docs.asp.net

拯救你的文档 – 【DevOps敏捷开发动手实验】开源文档发布

这是微软下一代 ASP.NET的技术文档,但吸引我的是它右上角的这个 Edit on Github 链接,点进去一看果然发现它的源代码是在GitHub上开源的。

拯救你的文档 – 【DevOps敏捷开发动手实验】开源文档发布

顺藤摸瓜,我找到了这个神奇的网站 https://readthedocs.org/

拯救你的文档 – 【DevOps敏捷开发动手实验】开源文档发布

研究一下,我发现使用GitHub + ReadTheDocs.org,终于可以满足我对技术文档的编写要求了:

– 你所编写的内容是与展现形式无关的:这里使用的格式是reStructuredText,这是一种类似Markdown的标记语言,比如:

文档源代码

拯救你的文档 – 【DevOps敏捷开发动手实验】开源文档发布

生成的HTML效果

拯救你的文档 – 【DevOps敏捷开发动手实验】开源文档发布

是不是很cool,特别是最下面的 练习列表 部分,只要直接引用相关的文件,就可以生成很漂亮的链接。

– 文档的源码仍然具备很好的可读性:相比HTML而言,reST格式的各种标记与内容融合在一起的,而不是环绕在你的源码周围的,比较一下表格的写法,你就知道我是什么意思了。

源码

拯救你的文档 – 【DevOps敏捷开发动手实验】开源文档发布

生成的HTML效果

拯救你的文档 – 【DevOps敏捷开发动手实验】开源文档发布

想象一下如果要编写这样的表格,用HTML代码如何写你就知道我的意思了。

– 文档可以以多种格式输出:reST可以被很容易的解析成HTML,PDF,ePub等多种发布格式,便于在不同的设备上进行访问,注意左侧的Downloads部分

拯救你的文档 – 【DevOps敏捷开发动手实验】开源文档发布

– 可以很容易的比较和跟踪内容变更:类似word/html这种文档,是很难进行版本比较的,但reST让着一切变得无比容易,而且你可以使用很简单的纯文本编辑器,不在需要笨重的Word。

使用Visual Studio Code进行内容比较

拯救你的文档 – 【DevOps敏捷开发动手实验】开源文档发布

– 可以借助git丰富的分布式协作来支持多人同时编辑,离线编辑,多分支,合并等复杂的协作场景。

这次的培训中所使用的文档编写流程:

拯救你的文档 – 【DevOps敏捷开发动手实验】开源文档发布

– 在我的github中建立了文档的主版本
https://github.com/ups216/vsalm-hols
– 在同事的github中fork我的主版本
– 可以同时编辑文档,并通过pull request互相分享最新的文档源码
– 在ReadTheDocs上建立了项目,同时设置了webhook,在向github push代码后直接部署到以下地址
https://vsalm-hols.readthedocs.org/

这样,我们可以同时编写文档,就算同时修改了一个文件,也可以很容易的diff其中的区别,进行合并。同时,发布以后又可以很容易的分享给感兴趣的人。ReadTheDocs上面的文档是可以自动适应不同的设备的:

在PC浏览器中是

拯救你的文档 – 【DevOps敏捷开发动手实验】开源文档发布

在手机浏览器中是这样的

拯救你的文档 – 【DevOps敏捷开发动手实验】开源文档发布

在这次的培训中,学员也普遍反映这种文档非常好用,便于分享,还可以通过github的issue来反馈问题。

好吧,最后给出这次发布的VSALM-HOLs动手实验文档链接,感兴趣的同学可以通过以下链接访问,或者在github上fork我们的文档,如果遇到问题也欢迎通过github给我们提issue,甚至提交pull request,谢谢。

文档链接:
https://vsalm-hols.readthedocs.org

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