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

[Rufus Pollock]

Dear Daniela,

This is great to hear.

Going forward it would be great to get the 'source' from you and we
could investigate the full-on i18n / translation method using sphinx
alluded to in my original email [1].

Rufus

[1]: http://sphinx.pocoo.org/latest/intl.html

On 13 April 2011 16:47, Daniela B. Silva <daniela at esfera.mobi> wrote:
> Hi everyone!
> Just some days before this thread started, we finished translating the open
> data manual to brazilian Portuguese \o/
> We made some changes to adapt the content to the brazilian reality
> (specially talking about licenses and access to information laws – we still
> don't have one, btw, but a bill is being discussed on the Senate today). We
> also added some info on brazilian projects made over open (or scraped) gov
> data, and tried to summarize our experience on organizing hackdays and
> engaging communities.
> I am sending you a PDF that is not final – as W3C Brazil Office is going to
> edit, review and publish it to be launched during a e-gov event in Brasilia
> this May (Rufus will be around).
> Now we also need to upload the open file to be edited on the web as an "on
> going project" – so maybe we can edit an updated portuguese version year.
> So, my question: the best way to integrate with you guys should be using
> sphinx?
> Daniela
> On Sun, Apr 10, 2011 at 6:36 AM, Antti Poikola <antti.poikola at gmail.com>
> wrote:
>>
>> 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
>>
>>
>> _______________________________________________
>> open-government mailing list
>> open-government at lists.okfn.org
>> http://lists.okfn.org/mailman/listinfo/open-government
>
>



-- 
Co-Founder, Open Knowledge Foundation
Promoting Open Knowledge in a Digital Age
http://www.okfn.org/ - http://blog.okfn.org/