[OPEN-ILS-DEV] Functions for updating the call number label or owning_lib associated with a copy

[Soulliere, Robert]

In regards to documentation, I wonder if an official procedures or documentation formats could be in place for developers to ensure that basic documentation is provided on purpose and basic usage for any new tools, functions or resources for Evergreen. I can see these db functions being very valuable for Evergreen users, but they would even be more valuable to the common user if they are well documented quickly so that they find their way to the official documentation so all users can find out about them. E.g. could it be required that any new evergreen feature be submitted with a one page AsciiDoc document explaining the purpose, usage and parameters of a feature/function/etc...

There was some discussion of AsciiDoc a while ago and it seems like a pretty good format for developer documentation, I am not sure if AsciiDoc or using the community wiki is easier for most developers? Perhaps standard documentation procedures could be discussed at a future developer meeting or has it already been discussed a lot in the past? Perhaps a standard template could be created for feature documentation provided by developers?

I am also still wondering about the purpose of this docs folder in the Evergreen repo:
http://svn.open-ils.org/trac/ILS/browser/trunk/docs

It looks like it has been a year since any of these files have been updated and there are only a few files there some of which look like remnants of where the official documentation repository was supposed to be. I wonder if this folder could be either better used for code/feature documentation or if this folder is an unnecessary remnant of days gone past?

Regards,
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
________________________________________
From: open-ils-dev-bounces at list.georgialibraries.org [open-ils-dev-bounces at list.georgialibraries.org] On Behalf Of Galen Charlton [gmc at esilibrary.com]
Sent: April 14, 2011 4:07 PM
To: Evergreen Development Discussion List
Subject: Re: [OPEN-ILS-DEV] Functions for updating the call number label or     owning_lib associated with a copy

Hi,

On Apr 14, 2011, at 2:54 PM, Dan Scott wrote:
> You snipped out the concerns I expressed about testing and maintaining
> these functions. Say what you will about the state of testing of the
> existing database functions, at least there's a chance that they will be
> exercised and deficiencies noted in day-to-day operation, as they are
> part of the general code. For the class of functions that Ben is
> proposing, however, I personally wouldn't want to see them become part
> of core unless there is a solid plan in place for documenting and
> testing and maintaining the functions; these seem much more likely to be
> susceptible to bitrot.

The routines in question are being actively used now, and would not stop being used just because they get added to core.  In fact, if they're sufficiently useful, they'll be tested more.  Even absent a formal test plan, it beats the status quo of a bunch of separate utility routines maintained by various Evergreen organizations.  But yeah, that isn't a substitute for a full test suite, so I'm work on a patch with some ideas towards fixing that.

Documentation?  Sure, there's no problem mandating that these be properly documented.

By the way, do you have any comments for Ben regarding the actual routine as proposed, regardless of where it gets placed?

Regards,

Galen
--
Galen Charlton
VP, Data Services
Equinox Software, Inc. / Your Library's Guide to Open Source
email:  gmc at esilibrary.com
direct: +1 352-215-7548
skype:  gmcharlt
web:    http://www.esilibrary.com/


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.