Chris Cormack a écrit :
On 19 March 2010 11:44, Irma Birchall <i...@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.
Another thing we have to consider is to document and formalize the way
things could be done.
a) Make more packages,
b) Should we Should we make API changes ? If so Is there a concensus to
gather about those ?
c) Make small functions and think reusable
For instance, a function which creates a subscription and also the next
waited serial should be splitted into two parts with a third function
that would join them.
Therefore, Objects making would be more handy
d) How to make and edit templates, how to gather pieces together ?
Should we split templates into parts ? One for ADD, one for display, one
for lists.
e) formalize the usage of js libs. What should we use Jquery or yui for
? ... Exemples like those posted by owen on his blog.
links to the installed features could be also interesting.
f) POD Documentation and usage of the POD test validator. (Is it
explained somewhere ?)
g) Tests making and proove or show how it works.
About Patches submission, also, define the steps you have to check
before/after sending a patch. For instance, I was proposed to send
patches to third parties for confirmation before sending to the list.
This looks good and reinforces the cooperation between us, but what if I
send and noone can have the time to look at what I sent ? Should I
withhold the patch or should I send onlist ?
Should we send or propose pullrequests ? Should we have some way to
discuss specifications, we tried to use the wiki for that, since
bugzilla is not a simple space for spec edition, but we had no comments
on our RFCs for 3.4. So we did what we proposed. But what if the release
manager tells ok you did that, that works for you, but not for the main
trunc, you have to do that way. Fair enough, but the time we devoted in
developping the feature could be down sized if we could speak and
exchange BEFORE developping a feature, not after.
In my opinion, all these points has to be part of the developer's side
documentation.
May be it is only wishfull thinking, but the more persons contributes
parts, the more we have to organize and state things and share views,
and have procedurals.
If three persons design the same feature (finedays for instance) who and
how, and on which criteria will we choose which part to include ?
If the feature is sponsored by 3 libraries worldwide, and one firm
throws his hat on that, but unreleased specification donot fit the third
library, which would like to add sane features, and a second firm has
told them we are developing that for you. Will the work done by the
first firm be "guaranteed" to make it in the trunc ? What about the
second firm, which has different and unreleased specifications too ?
Those are questions we should be able to adress not only with the kind
of manifesto Equinox made. But also with some clearly stated way to do
somewhere,
would it be in documentation, wiki or docs directory in source, I donot
have a precise idea of where to put it.
But we should have a stable link where we can refer to, even if it is
only work in progress and building.
My 2 cents
--
Henri-Damien LAURENT
BibLibre
_______________________________________________
Koha-devel mailing list
Koha-devel@lists.koha.org
http://lists.koha.org/mailman/listinfo/koha-devel
