[@OKau] opensourced tech specs

Wed May 20 05:02:37 UTC 2015

Thanks Steven B,
I will probably end up using git so don't take me the wrong way but while it is very developer friendly it is not general public friendly. My site users would like it a whole lot more if they could sign in using their social media accounts.  
I can see what you say about wiki's is true. I have trouble keeping up with my own which is why I was hoping for some kind of functionality on git that would allow me to write and update a spec like with code. Now I've thought of it I'm kinda looking forward to a spec. It will be awesome!
BTW, your post about what you hate about github comes up in the first page of google results on github ;-) I agree heartily with that post!
While I'm considering the long term aspects in case developers get involved, a more pressing need is to communicate and document with the general public in mind. They are my initial audience and devs may come along later. I also need to document a spec for my own coding. 
I can see the benefits of the git issue tracker for taking suggestions from users if I can only get people to use it. Better yet, I can take issues from Twitter followers and add them as issues myself & point them to the link, that way they'll know I have documented their suggestion. I can also link the issue tracker url into the specification itself. That gives me the transparency/accountability I'm looking for in the spec.
I guess I can put the spec on the wiki. Unless devs come along it will just be me coding it so only me writing & updating the spec. That might have advantages to in making it readable for the general public. I think the spec might be an important public document for what I'm doing. Thanks everyone for helping me think through the various issues around how to approach the task. 

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

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

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 - 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

_______________________________________________
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/56c9f638/attachment-0004.html>