[euopendata] Open Data Manual: updates and next steps

Fri Apr 8 11:54:24 UTC 2011

Hi All,

This an email about the Open Data Manual: <http://opendatamanual.org/>

If this is of interest read on otherwise please ignore :)

Below I outline where we are with the manual and the next steps we
should take. Please let me know your thoughts.

For those who don't get that far a new (work-in-progress) version of
the manual using sphinx doc framework [1] is at:

<http://assets.okfn.org/tmp/opendatamanual/index.html>

Source (please fork or request commit rights if you want to contribute!) at:

<http://bitbucket.org/okfn/opendatamanual>

Regards,

Rufus Pollock

## Current Status

1. The first of the manual was completed last Autumn during a book
sprint in Berlin
2. There was a period of community review with some additions.
3. The manual was posted up with some re-formatting and amendments in
a wordpress site in January.
4. It is now close to a basic v1.0

## Next Steps

There is lot we can do to make the manual even better, for example:

1. Translate it
2. Bulk out many of the sections, some of which are quite rudimentary
3. Include lots of examples
4. Include information on working with with data - getting it,
processing it, visualizing it etc. This would move the manual towards
a more data wrangler / data user audience

I think we can make a lot of progress on these quite quickly. The one
thing slightly holding us up at the moment is our current (tech)
framework and process for the documentation which I discuss next.

### The Documentation Framework

So far we have used a combination of google docs and wordpress. While
these were great starting point they have some severe problems,
especially if we want more people to get involved:

  1. Limited 'documentation' features (e.g. references between pages,
table of contents, indexes etc)
  2. Difficult to track changes (no source control) which makes it
hard to have more contributions and contributors (e.g. if someone now
updates the google docs it will be a nightmare to reintegrate that
into wordpress)
  3. Difficult to build to other formats e.g. PDF

I therefore propose:

  1. Move to using Sphinx documentation system [1]. Sphinx uses
restructured text whose basic syntax is close to markdown (markdown
derived from it) but has many more features that make it suitable for
something like this.
  2. Storing the documentation in a version control system
(mercurial). This way people can just fork to contribute.
  3. Possibly complementing this with a free-form wiki (for additional
material, early drafts etc)

I've already made a start on this by:

1. Moving all the source for the manual into a mercurial repo:
<http://bitbucket.org/okfn/opendatamanual>
2. Converted from markdown/html (we had a mixture) to use the sphinx
documentation system. You can see the results here (temporary
location):

<http://assets.okfn.org/tmp/opendatamanual/index.html>

[1]: http://sphinx.pocoo.org/