[@OKau] opensourced tech specs

Wed May 20 04:05:16 UTC 2015

Hi Rosie,

  I think you should probably keep things very simple.

  I would:
    - Forget using the github wiki,
    - Document your requirements via issue and bugs etc (I don't understand
what you mean by using Twitter for this)
    - Maybe have some "overall vision" in a README.md that you keep in the
repository alongside the code
    - Use unit tests to encourage programmers to get involved; i.e. have
some, and encourage their usage through ci builds and what-not (these
things can be added incrementally, if and when you need them).

  Happy to go into more detail on some of these if you wish. There's a very
small guide here -
https://guides.github.com/activities/contributing-to-open-source/ ; other
people may know of better guides.

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

-- 
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."
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.okfn.org/pipermail/okfn-au/attachments/20150520/e10b6b5a/attachment-0004.html>