I finally got around to doing this.

A couple of years ago I got sick of the way we were writing our documentation in Word and having to edit every document before each release to update the version number. I also got sick of the way we distributed discussion documents (again in Word) and people edited their comments into them. I’d get about eight copies back with conflicting comments. Finally, I got sick of the way I could never find any document a week after I put it into our ‘Document Hiding System’.

I put together a simple arrangement that keeps the documents in XML rather than Word. They can be committed to subversion along with the source code. We get change tracking and merging for free. And we can bulk. generate PDFs with any version stamp (or other change) we like.

After I got all this going I discovered DocBooks which is similar. But it has a lot more tags and is missing some features of mine. Fewer tags is easier when editing XML, even with a friendly editor like the XML plugin inside Eclipse.

We integrate document publishing into our software builds now.

Since I’ve got a blog on Google I thought I might as well use their O/S project repository.

Take a look at maduradocs. I’m not yet using their source repository, but everything you need is in the zip attachment. I welcome comments and suggestions.

Edit: I’ve subsequently moved this to a maven project on github.