[@OKau] opensourced tech specs

Wed May 20 04:42:36 UTC 2015

Hi Noon, 
I don't use Twitter for documentation - more for issues/bugs. Often when I post links to my site to Twitter if there is an error in the data or something else of note, my Twitter followers let me know. It is much easier for them than signing up to GitHub and often yields an immediate response. Also shows me people are paying attention to what I'm doing. I communicate with data.gov.au on Twitter too and the ACNC lately. Their responses are very good. 
Come to think of it I suppose data.gov.au is an example of crowdsourcing requirements and giving feedback - using Ideascale. I think there's some documentation in a related wiki.
There seems to be a difference between bug tracking or feature requests and documentation of code and between the needs of different audiences. I need to consider two different audiences- prospective coders and the general public. People do tend to know what they want, there's little uncertainty there. I'll have to think about the best approach to a document that meets the needs of the public and any coders including myself. 
Actually I can see a use for issue tracking for feature requests as it would allow me to mark them as duplicates or as unrealistic due to whatever reason.
I'll keep thinking about it.

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

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

Hi Rosie,
  I think you should probably keep things very simple.
  I would:    - Forget using the github wiki,    - Document your requirements via issue and bugs etc (I don't understand what you mean by using Twitter for this)    - Maybe have some "overall vision" in a README.md that you keep in the repository alongside the code    - Use unit tests to encourage programmers to get involved; i.e. have some, and encourage their usage through ci builds and what-not (these things can be added incrementally, if and when you need them).
  Happy to go into more detail on some of these if you wish. There's a very small guide here - https://guides.github.com/activities/contributing-to-open-source/ ; other people may know of better guides.

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

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 		 	   		  

_______________________________________________

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/be2c4a04/attachment-0004.html>