从 Word 到 Docbook, 最后用 Pandoc, 让程序员爱上写文档
写文档一直是程序员非常讨厌的工作, 甚至和改需求一样令人厌烦. 在程序员眼里比写程序还难, 即便强制执行下来文档质量也很难让人满意. 相信大多数公司写文档都是用 Word, 笔者也是用了 Word 写了好几个项目的文档. 架构, 设计, 运维等好几份, 呵呵, 即便是写的再好, 交给客户也基本是不看的. 一个文档是项目组内好几个成员编写的, 大家各写各的模块, 各自的实现, 然后一起合并, 合并时修改字体, 字号, 目录等, 第一次合并还好, 再升级几个版本后, 大家改了哪里, 没改哪里, 根本看不出来. 于是我就开始找一些文档工具. 个人一直看 Spring 的项目文档, Pdf 格式和在线 Html 格式都写的非常漂亮. 相信大家都很熟悉. 如下: 于是锁定了 Docbook 这个文档工具. Docbook 是支持 Maven 的, 在 pom 的 plugins 中加上支持 Docbook 的 plugin. ''' <plugin> <groupId>org.jboss.maven.plugins</groupId> <artifactId>maven-jdocbook-plugin</artifactId> <version>2.3.8</version> <extensions>true</extensions> <dependencies> <dependency>