[@OKau] opensourced tech specs

Wed May 20 01:40:29 UTC 2015

Thanks Noon, 
I'm a little confused about the various functionality of github. I was hoping I could create & maintain a working document the same way I could with code- which would make it an agile document. Clearly I was confusing wiki functionality with code repository functionality. Hmm.
Wiki's allow for transparent discussion although I see no talk pages available on the Github wiki. 
I like the issues feature but that doesn't really get added into a working document, does it? 
I think the general public is going to understand a wiki more so than an issue tracker but don't count that as a decision on my part, I'm just trying to think through the pros and cons of whatever options may be available. 
I suppose I could do all the requirements gathering during a set time frame, do up a spec myself and then develop that and then do another round of requirements gathering later and so on and so forth rather than continuously gather requirements. 
Or I could continuously gather requirements but only implement a set of them at a time so that I'm working off a particular version of the spec but the suggestions can keep coming in. I'm treating bug fixes separately to feature requests. Bugs obviously need to be fixed immediately so the issue tracker is fine for that although I often use Twitter for that purpose. 

Rosie Williams BA (Sociology)________________________________________
 NoFibs.com.au - Open Data Reporter | InfoAus.net - Founder and Developer 

Date: Wed, 20 May 2015 11:17:35 +1000
From: noonslists at gmail.com
To: okfn-au at lists.okfn.org
Subject: Re: [@OKau] opensourced tech specs

Some communities use wiki's to document technical specs, for example GHC: https://ghc.haskell.org/trac/ghc/wiki/Commentary
Note that with Wiki's on github, you don't approve changes, you just get to see them. But really, this is a feature.
The big problem with documentation is it going stale; so I'd see part of your job as project organiser to keep the documentation update, and in a standard format (when people do add to it, you may need to edit it).
Largely, though, you might be able to get by with just using issues; documenting features in there, and implementing as required.
Either way, I think hosting everything on a platform like github, and encouraging involvement in that way is quite a good idea.
--Noon

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 - Open Data Reporter | 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

-- 
Noon Silk, ن

https://sites.google.com/site/noonsilk/
"Every morning when I wake up, I experience an exquisite joy — the joy
of being this signature."

_______________________________________________
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/49e89768/attachment-0004.html>