Why a wiki does not work well for documentation - and what you can do about it

I've been working on moving documentation from the Open Babel wiki (Mediawiki) to a Sphinx-based system, and it's really so much better.

Wikis are great because they have a low barrier to contribution, make it easy to collaborate on documentation and (less importantly) have versioning. Wiki are rubbish because they don't impose a hierachical structure (they have some ideas about categories, but that's just not enough), pages get orphaned, and never get read. (They don't look great either, without a lot of customisation.)

Take, for example, the Open Babel wiki. Over the years a lot of effort has gone into creating content. However, there are many pages on the wiki I simply have never seen before because there is no clear path to them from the front page.

So, what to do?

As I said, I've been moving the docs into Sphinx (either manually, or using Pandoc). This uses a simple markup, reStructuredText (reST), to highlight headings, links and so forth. Most importantly it imposes a hierarchy - only pages that are included in a table of contents get incorporated into the documentation. The best part of all is that unlike a wiki (or at least, unlike Mediawiki) Sphinx can output not only HTML, but also LaTeX (for making PDFs) and HTMLHelp (for Windows CHM files).

But it's not a wiki any more, you're thinking. Well actually, that's where you'd be wrong. Through the magic of the internets, if you store your source code on Github, you have a de facto wiki, because reStructuredText is understood by Github and rendered reasonably well. You can click "Edit" right there on Github, edit the source and immediately see the result (and it's versioned of course).

An in-progress version of the Open Babel user documentation is available here, and you can check out the source code on Github (and fork it too, if you want).

Image credit: Ross Mayfield