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

Sat Apr 9 09:45:38 UTC 2011

Hi Rufus,

This is great! Should we move <http://assets.okfn.org/tmp/opendatamanual/index.html> to <http://opendatamanual.org/> soon?

Also: what exactly would I have to do if I wanted to start a german translation, could we make a small howto wiki page for reference? 

Regards
Daniel

On 08.04.2011, at 13:54, 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/
> 
> _______________________________________________
> open-government mailing list
> open-government at lists.okfn.org
> http://lists.okfn.org/mailman/listinfo/open-government