[@OKau] opensourced tech specs

Wed May 20 02:04:45 UTC 2015

It renders .md files in the repo as html pages.

--Daniel
On 20/05/2015 12:02 PM, "Rosie Williams" <budgetaus at hotmail.com> wrote:

> 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 <http://nofibs.com.au> - Open Data Reporter | InfoAus.net
> <http://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
>
> _______________________________________________
> 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/b2cef950/attachment-0004.html>