[@OKau] opensourced tech specs

[Steven De Costa]

The other thing to consider is whether a 'tech spec' is a doc that helps or
hinders.

I've seen the more scrum aligned approach working a little better -
features get written up with use cases and are somewhat independent of
overarching documentation. Where you need such overarching docs you make
them fit for purpose - 'this is the solution architecture' - 'this is the
paradigm for extensions/modules/plugins' - 'this is the core system'.

Trello is good for feature management and helps to keep things fresh by
ranking the work in the roadmap.

Post dev documentation might be important though, so you need things to
make sure that user docs, api docs and setup docs are always maintained as
features are implemented.

If working within a community then you might also need some documentation
for feature inclusion and release management steps.

A lot of these docs, or snippets, are done well on GitHub as they can be
forked as required in alignment with development forks. That way the docs
get patched and released as part of the software release rather than as an
afterthought.

Cheers,
Steven

*STEVEN DE COSTA *|
*EXECUTIVE DIRECTOR*www.linkdigital.com.au



On 20 May 2015 at 11:17, Noon Silk <noonslists at gmail.com> wrote:

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