本文版权归作者所有，欢迎转载，但未经作者同意必须保留此段声明，且在文章页面明显位置给出原文连接，否则保留追究法律责任的权利。
转载自夜明的孤行灯
本文链接地址: https://www.huangyunkun.com/2019/12/19/software-document-management-and-publishing/
文档对于软件来说是非常重要的一部分，特别是对于开源软件来说，在接触源代码之前，一般会先接触文档。
文档可以给新的使用者一个清晰的快速上手说明，也可以给已有使用者提供更多细节上的信息，帮助使用者更好的使用各种特性。
我认为一个合格的文档应该满足以下几个要求：
- 易于编写，由一种标准格式驱动，比如asciidoc或者markdown也可以
- 支持文档版本化
- 支持文档搜索
- 对于多语言翻译友好
- 支持多种格式用于离线浏览（比如pdf或者epub格式）
常用的做法有以下几种：
- 使用专用的网站/文档构建工具
- 选定一种文本格式，并使用相应工具链处理
- 文档直接附加在分发物中
使用专用的网站/文档构建工具
这是一种相对省心的方案，一般可以直接构建完整的网站，并附带对于文档的支持。
比如react-native使用的docusaurus，这是一个全套解决方法。对于文档本身使用markdown书写，对于多语言翻译使用的是crowdin工具，搜索支持来源于algolia。对于不同语言还有版本的支持都是基于目录的。而多版本切换入口在页面顶部的logo旁。
以react-native为例，版本切换在https://facebook.github.io/react-native/versions中，而不同版本路径如下：
https://facebook.github.io/react-native/docs/getting-started
https://facebook.github.io/react-native/docs/0.60/getting-started
类似的工具还有docsite、vuepress、docsify等，但是对比与docusaurus多多少少有一些功能缺失。
选定一种文本格式，并使用相应工具链处理
上面一种其实是网站+文档解决方案，如果只是需要文档，那么方案可以更纯粹一些。
可以参考spring-boot的方案，在spring-boot的项目中有一个spring-boot-docs文档，其中有adoc为后缀的文件。这些文件都是asciidoc格式的，通过asciidoc的maven插件生成对应的html、pdf、epub格式的文档，并上传到对应目录，而文档版本引导页面是自己独立编写。
这种操作的优势在于文档输出格式多，且网站样式自由度高，理论上只需要加上不同版本的链接即可。
文档直接附加在分发物中
对于功能比较直接的，可以直接将文档附加在分发物中，比如放在readme中，或者作为软件的一部分，比如命令行工具的help指令。这种一般针对于功能直接的小型软件。
Dubbo文档的管理
Dubbo目前的文档基于docsite建设，语法使用markdown语法，支持多语言（目录模式）。唯一的缺少的主要是两个
- 文档版本化
- pdf、epub等格式导出
版本化
文档版本化可以考虑简单思路就是仿造docsite用docusaurus一样的方式支持版本化。
目前Dubbo文档源文件目录如下：
而支持版本化的目录结构如下：
| Version | Tag | URL |
|---|---|---|
| 1.0.0 | 1.0.0 | docs/1.0.0/doc1.html |
| 1.0.1 | 1.0.1 | docs/1.0.1/doc1.html |
| 2.0.0 | current | docs/doc1.html |
master branch | next | docs/next/doc1.html |
而对于已有版本，使用version.json文件保存即可。
离线浏览
docsite目前只提供web模式浏览，对于文档而言，导出可用的pdf用于离线浏览也是有必要的。
markdown格式导出到pdf的工具很多，但是需要结合目录情况导出合适的格式。
迁移到asciidoc
迁移到asciidoc可以更好的支持不同格式的文档，但是对于文档多版本还是需要采用脚本等手动处理，考虑到目前网站已经使用docsite驱动，实际意义不大。
本文版权归作者所有，欢迎转载，但未经作者同意必须保留此段声明，且在文章页面明显位置给出原文连接，否则保留追究法律责任的权利。
转载自夜明的孤行灯
本文链接地址: https://www.huangyunkun.com/2019/12/19/software-document-management-and-publishing/