[OPEN-ILS-DOCUMENTATION] documented developmnt

[Grace Dunbar]

  Hi Robert (and everyone),
I'll jump in a bit from the perspective of Equinox and hopefully we can 
find a great solution for everyone.

I think we have two sides of the equation; contracted development with a 
company like Equinox, or community development.  Obviously, the solution 
we come up with has to have a standard that fits both groups.  And I 
believe that there is a common point at which both kinds of development 
meet - at the commit stage.  Working backwards, perhaps the core 
developers need to informally adopt the stance that no code is committed 
without some kind of documentation.  But, of course, that is where it 
gets tricky.  If the commit is a fix to some bug that only manifests 
itself in a random database level error but doesn't display to the user 
and doesn't affect performance, how much documentation does that get?  
Is documentation only for features with User Interfaces through the 
staff client or OPAC?  Just thinking about it gives me a headache - I'll 
let DIG and the developers haggle on that.

Why aren't vendors providing documentation automatically?  Historically, 
Equinox has provided many of our clients the option of paying for the 
end-user documentation of the features we're creating.  Almost every 
single one of our clients has declined this option.  We generally don't 
produce end-user documentation for ourselves internally, so the 
documentation goes unwritten. However, we have recently made a decision 
to include documentation in all development contracts - it is no longer 
an option.  We feel the clients and the community will benefit greatly 
from this moving forward.  We generally can't provide documentation any 
earlier than after the code has been officially released in a specific 
version of Evergreen.  Generally, this isn't due to any contractual 
issues (although I think that the group paying for the work does have a 
right to vet the documents first), it's simply because things change, 
sometimes right up until the last minute.  Development is planned out in 
general and the specifics of how a screen is laid out or what's in a 
dropdown menu are often the very last things to be finalized.  Sometimes 
these changes are developer driven and sometimes it's the client - but 
providing documentation at any stage prior to the final tested version 
would be misleading at best.  That said, Equinox is aspiring to provide 
better notes to the community of features that are in development.

Now, getting the documentation out at the time of release?  That should 
be an achievable goal for Equinox; however, I can't speak for the 
community developers - and all the developers should be held to the same 
standard.  Since there isn't a "client" who is commissioning the work, 
perhaps the community developers could use DIG as they go along their 
development path to provide testing and documentation.

Thanks for opening the conversation,
Grace

On 2/8/11 1:34 PM, Soulliere, Robert wrote:
> Hi All,
>
> During the DIG meeting Dan proposed that the DIG could suggest to the Evergreen community that any new contracted feature development should include docs to be submitted to the DIG as part of the development. I wonder if we could discuss this here and broaden the topic a bit to see if it is possible to get  documentation on new features into the official documentation more quickly?
>
>   I would like to offer an open-ended question:
>
> Is there  anything that DIG can do to help get documentation on new features into official documentation as they are developed so all organizations can get the information they need to learn about and use the new features when the install or upgrade Evergreen?
>
>   It would seem that these new features would have something written somewhere -- even rough notes? Is there an economic or contractual  reason why these cannot be shared with the general Evergreen community at an earlier stage by either the developers of the features, users of the new features or trainers for the new features?
>
> Robert
>
> Robert Soulliere, BA (Hons), MLIS
> Systems Librarian
> Mohawk College Library
> robert.soulliere at mohawkcollege.ca
> Telephone: 905 575 1212 x3936
> Fax: 905 575 2011
>
> This E-mail contains privileged and confidential information intended
> only for the individual or entity named in the message.  If the reader
> of this message is not the intended recipient, or the agent responsible
> to deliver it to the intended recipient, you are hereby notified that
> any review, dissemination, distribution or copying of this communication
> is prohibited.  If this communication was received in error, please
> notify the sender by reply E-mail immediately, and delete and destroy
> the original message.
> _______________________________________________
> OPEN-ILS-DOCUMENTATION mailing list
> OPEN-ILS-DOCUMENTATION at list.georgialibraries.org
> http://list.georgialibraries.org/mailman/listinfo/open-ils-documentation

-- 
Grace Dunbar
COO
Equinox Software, Inc.
gdunbar at esilibrary.com
1-877-OPEN-ILS  x5579
www.esilibrary.com