开源软件文档管理与发布

19 12月

文档对于软件来说是非常重要的一部分,特别是对于开源软件来说,在接触源代码之前,一般会先接触文档。

文档可以给新的使用者一个清晰的快速上手说明,也可以给已有使用者提供更多细节上的信息,帮助使用者更好的使用各种特性。

我认为一个合格的文档应该满足以下几个要求:

  • 易于编写,由一种标准格式驱动,比如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文档源文件目录如下:

而支持版本化的目录结构如下:

VersionTagURL
1.0.01.0.0docs/1.0.0/doc1.html
1.0.11.0.1docs/1.0.1/doc1.html
2.0.0currentdocs/doc1.html
master branchnextdocs/next/doc1.html

而对于已有版本,使用version.json文件保存即可。

离线浏览

docsite目前只提供web模式浏览,对于文档而言,导出可用的pdf用于离线浏览也是有必要的。

markdown格式导出到pdf的工具很多,但是需要结合目录情况导出合适的格式。

迁移到asciidoc

迁移到asciidoc可以更好的支持不同格式的文档,但是对于文档多版本还是需要采用脚本等手动处理,考虑到目前网站已经使用docsite驱动,实际意义不大。

发表评论

电子邮件地址不会被公开。