[open-data-manual] Participation Guide created

Wed Jun 1 05:33:07 UTC 2011

Hi all,

I've spent some time drafting a guide for people wanting to help out
with the project.

Markdown source follows. The guide is also available on the project's
wiki (https://bitbucket.org/okfn/opendatamanual/wiki/Participation_Guide)
and its original source is Etherpad
(http://opengovernmentdata.okfnpad.org/open-data-manual-participation-guide).

Feedback welcome!

+++++++++++++++++++++++++++++++++++
Open Data Manual - Participation Guide
+++++++++++++++++++++++++++++++++++

Note: Like the manual itself, this guide is still being developed. You
are very welcome to help out.

Ad-hoc contributions
====================

Ad-hoc contributions are very welcome. If you've noticed something
that is missing or could be improved, then please notify the team.

You have two main options:

* email your contribution to the mailing list
http://lists.okfn.org/mailman/listinfo/open-data-manual
* create a ticket in our issue tracker with your contribution
https://bitbucket.org/okfn/opendatamanual/issue

Who should contribute
=====================

Everyone. Well, at least everyone with an interest in open data. Our
primary goal is to create a resource that has practical information
for people who are learning about or using open data.

Places to start
===============

**Read the manual**

As you read through, ask yourself a few questions:

* can we reduce any waffle?
* are there any relevant links that would be wortwhile mentioning?
* does content flow properly?
* do any areas need expanding?

**Read through the tickets**

Issues are emerging all of the time on our issue tracker:
https://bitbucket.org/okfn/opendatamanual/issue. Feel free to allocate
yourself to a ticket and start writing.

**Bring in other contributors**

If you know anyone who has an interest in access to or the analysis of
data, please forward them to the mailing list. As the community
expands, it will encounter signficant network effects.

Our tools
=========

About them
----------

The team has a small set of technology tools, designed to make life easier.

**Project management**

Bitbucket https://bitbucket.org/okfn/opendatamanual
Mailing list http://lists.okfn.org/mailman/listinfo/open-data-manual

**Writing**

Mercurial (hg) http://mercurial.selenic.com/
Sphinx http://sphinx.pocoo.org/
reStructuredText sphinx.pocoo.org/rest.html

Bitbucket is the closest thing that the team has to a project
management tool. It houses the team's wiki as well as our issues. The
term project management is slightly over the top however. We use the
system to avoid duplicated effort, rather than marshalling people to
do someone else's bidding.

Our mailing list is where the bulk of the team's communication occurs.
We aim for the atmosphere to be productive, but not intimidatingly
technical.

Mercurial (commonly known by its command line tool hg) software that
was designed for software developers to manage the problem of multiple
people working on the same thing together. We can make use of that
technology in our area too.

reStructuredText or (reST) is a way of writing plain text files that
is sensible to both people to read as well as computers. We don't make
people write in HTML pages. reST is a way for people and computers to
strike a middle ground between readability and structure.

Sphinx takes the content that is written in reST and shared with hg
and turns it into web pages or files for ebook readers. Again, this is
a tool which has its origins within software development. Despite its
geek origins, it suits non-geek purposes very well.

Installing them
---------------

Most of our tools are web based. However, hg and Sphinx are not. If
you are running Ubuntu, you can install them via the command line:

    sudo apt-get install hg python-sphinx

Editing the manual on your computer
===================================

Once you have all of the software running, it is quite easy to get
your own copy of the manual.

Open a terminal and type:

     hg clone ssh://hg@bitbucket.org/okfn/opendatamanual
     cd opendatamanual
     make html

You now have a copy of the manual that you can view in a web browser.
The source text of this manual lives in the `source` directory:

    cd source

You can happily edit these files knowing that those changes will not
impact others.

Submitting improvements
=======================

If you are familiar with source control, the preferred option is to
make "Pull Requests" bia Bitbucket. However, if you don't feel
comfortable with that, then just email the file that you have changed
to the mailing list or attach it to a ticket.

Tim McNamara
Professional \\  paperlessprojects.com
Personal \\  @timClicks  |  timmcnamara.co.nz