[@OKau] opensourced tech specs

Wed May 20 02:02:27 UTC 2015

Hi Alex, 
Are you saying that github can generate a site based on the code from the .md or that it generates documentation? 
thanks btw,

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

> From: maxious at gmail.com
> Date: Wed, 20 May 2015 11:48:54 +1000
> To: okfn-au at lists.okfn.org
> Subject: Re: [@OKau] opensourced tech specs
> 
> 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
> >
> _______________________________________________
> 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/7ad2c006/attachment-0004.html>