[open-government] [euopendata] Open Data Manual: updates and next steps

Sun Apr 10 09:36:05 UTC 2011

Great work Rufus,

I'm new to Bitbucket and Mercurial (I have played a bit with texts in 
Github), but I'll check if I manage to get sphinx working for me.

-Jogi

On 04/08/2011 02:54 PM, Rufus Pollock wrote:
> 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/
>
> _______________________________________________
> euopendata mailing list
> euopendata at lists.okfn.org
> http://lists.okfn.org/mailman/listinfo/euopendata