实践记录 - 软件开发文档编写

先说方法与结论：采用腾讯/金山共享文档协作编写软件的用手册文档。产品源代码在gitlab仓库，采用gitlab的wiki编写软件开发文档；用pandoc工具将wiki的md文档转换为html网页；用HugeCHM将html页面打包为chm帮助文档。

（一）Gitlab Wiki

Gitlab wiki是gitlab自带的多人协作文档系统，用于开发人员记录关于软件的方方面面的内容。其中就可以包括开发文档。gitlab的wiki本质上也是一个gitlab仓库，可以克隆到本地，这个仓库和代码仓库是2个独立的不同仓库。wiki的默认入口文件为Home.md，文件名不能改变。

gitlab的wiki仓库

开发人员加了功能之后可以随手更新文档的现有页面，也可以新建一个新的页面。来阐述ta的开发的设计、约定、最佳实践等。

注：github也有wiki功能。

wiki的好处：

1. 组织结构更自由，可以存在若干主题页面，篇幅长短不限，页面的目的可以是为说明清楚一个问题，开发者能专注于当下这个页面的编写，不受一个总文档其他部分的干扰。
2. 每一个页面都有版本更新记录，方便追溯。
3. md格式，交叉引用比word方