Giving documentation a ReST

Categories: Documentation Created by François Suter

Several months ago we announced the migration of the official documentation to DocBook. We are now turning to reStructuredText. Read on to understand why.

The main aim of the documentation migration project was not so much moving toDocBook as moving away from OpenOffice. Although it is possible to produce perfectly fine manual with the latter, it has many disadvantages for us, in particular the difficulty of collaborating and the impossibility to version files properly, to name a few. Of course we needed something to move to. Switching to DocBook had been in the air for a long time. Actually the TER already converts OpenOffice files to DocBook, en route to HTML. We also aimed to converge with the FLOW3/Phoenix team, which was already using DocBook.

This is how we got started. We learned quite a bit about DocBook, we started writing some sample documents to get a feel for the format. Tom Schraitle, a DocBook expert from the OpenSUSE community, came over and helped and advised us. We seemed to be on a straight course, but the FLOW3 team came knocking on the door again: after writing quite a bit of DocBook, they had some misgivings about it, especially about the complexity of the format. They feared it would be a major hurdle preventing many people from contributing to documentation. They wanted to have a shot at trying reStructuredText (ReST), another widespread documentation format (used - for example - by the Python project).

After a somewhat heated conference call, we decided that the FLOW3 team would go ahead and experiment with ReST in the course of releasing FLOW3 beta1. They would then give their feedback in the documentation mailing list and we would jointly take a decision. The DocBook migration was put on hold for a couple of weeks (it had been on a lull during the summer anyway).

Eventually the FLOW3 team came back with a very positive experience with ReST. Their feedback was discussed and evaluated. The final decision was to switch. This means some loss of the work done for DocBook, but we feel that going with ReST will be more fruitful and it was not too late to change our minds.

The main point in favor of ReST is the ease of writing. Indeed the format is comparable to a wiki syntax. While working on the DocBook migration we had an still unanswered, important question: what to do with extension authors? It seemed impossible to require them to write their manuals in DocBook. Not so with ReST. In general the build chain to render the manuals seems simpler, as does the cross-linking mechanism.

The migration goes on!