Write the Docs: Sebastien Goasguen – Going from Publican to Read the Docs

I’m at Write the Docs today in Budapest and will be post­ing notes from ses­sions through­out the day. These are all posted right after a talk fin­ishes so they’re rough around the edges.

Sebastien was the first talk after break. He works on Apache CloudStack and is a committer to the Apache project.

Apache CloudStack moved from an old documentation tool, Publican and DocBook, to Read the Docs. They wanted to bring in a greater sense of community with their documentation and make it more accessible.

The old tool, Publican, is a build tool for documentation written in the DocBook format. DocBook itself is a XML schema suited for books and papers; it’s not necessarily meant for web-based docs. The editing tools, though, are either technical like vi or expensive. For an open source project that’s a no-go. They were also running in to issues around localization, internationalization, hosting, and attracting new writers.

Using Read the Docs they were able to move toward using reStructuredText for writing. It’s an easy-to-read, WYSIWYG plain text markup syntax parser. The problem, though, is that they had 40,000 lines of XML to transform in to reStructuredText. Their lifesaver was pandoc. This let them convert all the files without needing to rewrite everything.

Sphinx allows them to build their documentation sites and projects. The hosting is handled through Read the Docs. One of the killer features for them was the button on each doc that let people edit on GitHub. Given that Apache CloudStack’s goal was to increase their contributor base this was vital. It dropped the barrier to entry for new contributors. They’re now starting to see drive-by contributions to docs, which is great.

The one last hurdle for them is translation. With large communities in China and Japan it’s key for the project to make translation easy. Handily, with Sphinx, they can do this. They use the same tool that Markus talked about yesterday. They now have more people contributing translations than they do documentation.

Ultimately changing documentation format gave Apache CloudStack docs which were good looking, easy to contribute to, supportive of localization, and much much more.