[@OKau] opensourced tech specs

Wed May 20 04:42:24 UTC 2015

Hi Rosie,
  Repeating what some others have said a bit, but I think simply starting a
GitHub repo per project works pretty well. General pattern:

- create the repo
- add a README explaining the vision
- commit code, using commit messages to further expand on the "why we're
doing this"
- add issues as you go, either just to document things you haven't done
yet, or even to document things you're about to do, then close
- have discussions on issues. This seems to work really well, in my
experience - it's easy to @ping people to bring them into a discussion, and
you get email notifications of relevant stuff.
- encourage others to submit pull requests

I've started a couple of projects on GitHub and had collaboration from
others (eg
https://github.com/okfnau/open-council-data/issues?utf8=%E2%9C%93&q=is%3Aissue),
and I've contributed small pieces here and there to maybe a few dozen
repos. Browsing through current issues and the discussion on them is an
excellent way for a newcomer to understand the goals, mode of working, and
general culture of each project.

In general, I find wikis a bit of a pain - they really do go out of date,
then no one wants to touch them. For NationalMap, we use the wiki for a
couple of specific bits of documentation (eg
https://github.com/terriajs/terriajs/wiki) , but you have to be careful to
avoid them being a dumping ground of uselessness.

It's also possible (but a bit orthogonal to the above) to host static sites
directly on GitHub (just make a branch called gh-pages), eg:
http://okfnau.github.io/PTV-API-Swagger/dist/index.html

The bit that Alex mentioned about .md pages on GitHub turning into a
website (http://okfnau.github.io/open-council-data/) is actually not GitHub
functionality - that's a library called FlatDoc. I'd still highly recommend
using MarkDown as a documentation format, though, because it does render
well when viewed in GitHub, and is generally very developer friendly.

Steve

On Wed, May 20, 2015 at 10:57 AM, Rosie Williams <budgetaus at hotmail.com>
wrote:

>  Hi all,
>
> I'm thinking about how to go about my future projects. I intend to
> crowdsource requirements from the public. I anticipate that my projects
> (and feature requests) will become more complex and involve more datasets
> as people realise the potential of this.
>
> Given that I intend to source many requirements publicly through virtual
> and face to face events, and given the anticipated complexity of the
> projects I'm wondering if I should have an open technical specification
> along with open sourcing the code.
>
> I was wondering what people think about using git hub for this, perhaps
> the wiki? Are there better options? Ideally I'd like the growing community
> interested in any of the data/projects to be able to move easily between
> discussing things publicly and if they are so inclined, adding to the tech
> spec.
>
> I'm assuming I'd still have the option to add or reject changes if I need
> that. I haven't used git much for working with other people, at least not
> in a truly collaborative fashion (more like each person in their own corner
> doing their own thing & submitting updates). However I'm envisioning a very
> collaborative approach to my future projects so I need to think about how
> this affects documentation. I haven't used documentation with my other
> recent projects as it's just been me but things are getting pretty complex
> now so I think I'll need it.
>
> Examples of the kinds of projects are coming online at http://ausgov.org
> I put up the ACNC charities data yesterday at
> http://www.ausgov.org/commonwealth/charities/index.php and I'm linking in
> charity name & ABN's with QLD DCCSDS funding results & Commonwealth DSS
> grants funding results. There's also tenders data results that can be
> added. While I can't run queries across any two of these databases on my
> shared server as they take too long (can be done on my local server though)
> , I can link from one to the other using urls created through search
> results to define parameters.
>
> So you get this kind of result
> http://www.ausgov.org/commonwealth/charities/index.php?ABN=11062802797&submit=Go Then
> you can click through to see the result from the grants funding database-
> at least with the QLD DCCSDS data. (Commonwealth grants site is not
> linked in as of writing but the db is there to produce a result).
>
> thanks in advance,
> Rosie Williams BA (Sociology)
> ________________________________________
>  NoFibs.com.au <http://nofibs.com.au> - Open Data Reporter | InfoAus.net
> <http://infoaus.net> - Founder and Developer
>
>
>
>
> _______________________________________________
> okfn-au mailing list
> okfn-au at lists.okfn.org
> https://lists.okfn.org/mailman/listinfo/okfn-au
> Unsubscribe: https://lists.okfn.org/mailman/options/okfn-au
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.okfn.org/pipermail/okfn-au/attachments/20150520/938d561a/attachment-0004.html>