[@OKau] opensourced tech specs

Wed May 20 05:04:08 UTC 2015

Hi,

A few points on using GitHub:

* Yes, aside from the GitHub wikis (which I don’t use, I think wiki is a horrible format), you can publish to GitHub Pages (https://pages.github.com/ <https://pages.github.com/>). I’d strongly recommend an approach that combines Issues and GitHub Pages. You might want to get familiar with Jekyll (http://jekyllrb.com/ <http://jekyllrb.com/>), which is the engine used by default to render a GitHub Pages website (you can use any static files, or other site site generators, but there is a clear advantage to using Jekyll in cases of collaborative input, more on that below).

* You might be surprised to know that at Open Knowledge, we use GitHub Pages extensively, and especially on content-heavy projects where we want to engage non-technical users.
    * Open Data Index (http://index.okfn.org/ <http://index.okfn.org/>) is served entirely from GitHub Pages
    * Open Data Handbook (http://opendatahandbook.org/ <http://opendatahandbook.org/>) is served entirely from GitHub Pages

The Index is a bit less appropriate as an example, as I wrote a bunch of custom logic for that - it is more like a full application that happens to be served statically, and some of our content team work with it

The Handbook is a good example though. The project is mostly run without developers, it has a contribute section that tries to explain GitHub, Jekyll and Markdown for non-technical users (http://opendatahandbook.org/contribute/ <http://opendatahandbook.org/contribute/>), and by following the guide, we have content teams from around the world using GitHub Issues to report bugs in the book, and using Pull Requests to add translations and content enhancements.

I would not say it is completely easy for anyone to get into this flow: I’d say that using Issues is easy enough, but the experience of Pull Requests, while it is working, is probably a bit hard for some potential contributors.

There is this tool: http://prose.io/ <http://prose.io/> which apparently makes working on top of Github with content even easier, but I have not tried it yet.

> On 20 May 2015, at 07:42, Steve Bennett <stevage at gmail.com> wrote:
> 
> 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 <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 <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 <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/ <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 <mailto: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 <http://ausgov.org/> I put up the ACNC charities data yesterday at http://www.ausgov.org/commonwealth/charities/index.php <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 <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 <mailto:okfn-au at lists.okfn.org>
> https://lists.okfn.org/mailman/listinfo/okfn-au <https://lists.okfn.org/mailman/listinfo/okfn-au>
> Unsubscribe: https://lists.okfn.org/mailman/options/okfn-au <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/0522da76/attachment-0004.html>