We’ve just gone live with a new way of publishing and maintaining documentation for Percona Server and Percona XtraBackup. We are now using Sphinx to generate the documentation that we publish on the web site. Sphinx was originally created for the new Python documentation, and has won us over due to the simple markup, ease of cross-referencing, ability to keep our documentation source along with our source code and support for multiple output formats.
This moves our documentation workflow to be the same as for source code. A developer (or writer) will create a bzr branch on launchpad and submit a merge request. This means documentation review now goes through the same system as code review.
We have also set up a Jenkins job to automatically update the documentation on the percona.com web site when changes are made to the source repositories. This means that bug fixes and improvements to the documentation can transparently and automatically be published with a minimal amount of turn-around.
An added benefit for XtraBackup is that it it will enable us to easily share documentation for the Drizzle version of XtraBackup as Drizzle uses Sphinx for its documentation too. The new setup for Percona documentation was based on that of the Drizzle project.
The end result? Better and more frequently updated documentation.