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

Wed Apr 13 15:47:12 UTC 2011

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
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.okfn.org/pipermail/open-government/attachments/20110413/f130489e/attachment.html>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: cartilha.pdf
Type: application/pdf
Size: 580380 bytes
Desc: not available
URL: <http://lists.okfn.org/pipermail/open-government/attachments/20110413/f130489e/attachment-0002.pdf>