Open Data Manual/Technology Options

This page looks at the technology behind delivering the manual.

Requirements

 * Easy to edit (offline and online?)
 * Revisioning
 * Partitionable
 * Exportable to different formats
 * Deploy result at your own site

Nice to have


 * Looks pretty on paper
 * Simultaneous editing (not needed if we have partitioning)
 * Translatable?

Sphinx + Mercurial
The system that's currently being used. Well known in the Python world. Supports ReST, a very complete markup-less text format for content.

One of the advantages with a plain text backend is that it's possible for people to subscribe to the version control and then easily contribute more content. This makes offline editing and contributions.


 * + ultra-simple using standard open-source tools
 * + power of full version control
 * + get lots of formats
 * + Designed for 'books' (i.e. table of contents, index)
 * + sphinx is getting better and better (with support for latex etc)
 * + used by lots of other (Python) projects
 * - high barrier to entry (Cloud9 or Github wiki to make things friendlier)
 * - default themes are poor
 * - oriented to software

DokuWiki (or Mediawik or Mindtouch)
A PHP wiki specialising in documentation. opendatacookbook.net uses the system to good effect. IMHO much nicer to use than MediaWiki.


 * + mature
 * Sophisticated collaborative content solutions
 * - more wiki than book ...
 * e.g. table of contents generation ...

Teambox
From first-hand experience, teambox.com provides a very good service if you have people who are willing to get their heads around how it operates. The software is a team/project management tool. However, it provides a fairly good and intuitive section for "pages". This means that we could have a teambox for the project. As people read through the manual, they are immediately connected with authors and the rest of the community. It's AGPLed software, which means that OKFN could install its own isntance.


 * + collaboration
 * + ticketing system /todo lists built in
 * - no offline editing
 * - Is it full open-source?
 * - not really a document editor
 * - export quality poor

Booki
This is the tool that currently runs FLOSS Manuals. One of its biggest strengths is its export capability. The Open Data Manual could easily be exported and produced by Lulu.com and distributed on paper. This may make the manual more accessible to people who are yet to be completely confident with tech.


 * Homepage http://www.booki.cc/
 * Example CSS & render http://blog.booki.cc/2011/04/example-css-from-sourcefabric/


 * + Book oriented and partitionable
 * + Online editing
 * - Maturing platform
 * - Bespoke solution
 * - lack of user experience
 * ? can we export html satisfactorily

LaTeX

 * Isn't a solution it's a format -- (mercurial + latex + export to html / pdf...)
 * More related to another option

Wordpress

 * + very standard
 * + blog capabilities
 * + integrated with existing OKF system
 * +? good SEO? e.g. metadata
 * - limited to markdown or pure html
 * - not designed for books though some book themes
 * Getting page order right is really tedious
 * - poor version control
 * - how do you do translations
 * - no easy export to e.g. pdf ...