[Koha-devel] Developer Documentation -

[Chris Cormack]

On 19 March 2010 11:44, Irma Birchall <irma at calyx.net.au> wrote:
> Hi Reed
>
> As we want to bridge the gap between developers and users and assist users
> to become (or engage more with) developers and developers to become better
> users, is it wise to repeat something you say "I've never seen it done
> well"?
>
What Reed meant, is he has never seen developer documentation done
well. Which I have to agree with him I haven't either, this isn't to
say not to try just that it is a hard problem to solve.

> My suggestion is that one adds to the 4 categories of developer
> documentation you list, 2 important documents: the "User Guide" and "Client
> Requirements Guide"  to frame a more complete picture.
>
> Just like adjusting the size of the font to suit our visual needs when
> reading web pages, if the reader could adjust the documentation reading
> level to suit their information needs by clicking on the - or + signs like
> when viewing Google maps .... that would be cool!
>
> Then we truly would document requirements and knowledge from the library
> patron, the library staff and the amazing Koha developers all in one multi
> layered manual.
>

Yep, that's the easy bit, getting developers to write it is the trick.
Lars had a suggestion and I agree
to quote him "ideally I would see the dev docs in the source tree, and
a culture of updating them whenever the code changes"

It's building that culture that is the tricky bit. Dev changes so fast
that we need to make sure the doc changes with it, having it in the
same place as the code and having an expectation that patches that
change code, change the doc too seems like one of the few ways to make
it happen.

Chris