[@OKau] opensourced tech specs

Wed May 20 01:48:54 UTC 2015

You can use the Github wiki but you can also have Markdown (.md) files
in your git code repository.

This is what the Open Council Data specifications are using
https://github.com/OKFNau/open-council-data and if they are in code,
people can create issues or send pull requests where you (the project
owner/team) can comment on and approve changes when appropriate
(unlike a wiki where the change is immediate).

eg. This issue discusses a change of date format
https://github.com/OKFNau/open-council-data/issues/15 and then once
agreed the specification is updated in the code
https://github.com/OKFNau/open-council-data/commit/ea2b6639f0c1290f754bf0fdef1e095296925629

These Markdown files also feed into a feature called Github Pages
where it will make a website for you based on the .md files:
https://pages.github.com/

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
>