[OPEN-ILS-DOCUMENTATION] [OPEN-ILS-GENERAL] DIG version of Acq docs (was: Acquisitions and Serials Documentation Drafts Now Available)

[Mike Rylander]

On Sun, Mar 6, 2011 at 11:36 AM, Sharp, Chris
<csharp at georgialibraries.org> wrote:
>
>
> ----- Original Message -----
>> From: "Lori Ayre" <loriayre at gmail.com>
>> To: "Dan Scott" <dan at coffeecode.net>
>> Cc: "Evergreen Discussion Group" <open-ils-general at list.georgialibraries.org>, "Lori Bowen Ayre"
>> <lori.ayre at galecia.com>, open-ils-documentation at list.georgialibraries.org
>> Sent: Sunday, March 6, 2011 10:38:28 AM
>
> <snip>
>
>> > Well, IMO, documentation that institutions pay to have written for
>> > would ideally be developed as part of the community process, the
>> > same
>> > way that the software itself is developed as a community process.
>> >
>> Okay. I guess I considered what was proposed (accept the draft
>> provided as is and edit as needed) an acceptable community process. Am
>> I missing something? Are you suggesting a different workflow for
>> documenting new development?
>
> </snip>
>
> I think what Dan is saying (and I agree, if so) is that when GPLS (or whoever) contracts with ESI (or whomever) for documentation, that the process of writing the documentation is as open as the process of writing the software.  That is, rather than having the documentation vendor work behind closed doors, then releasing the (mostly) finished documentation in one big hunk, the documentation vendor would be committing drafts, changes, additions, etc. all along so that the community could track it and use what tidbits are provided with the understanding that it is (like the software itself) in process, subject to change, and not ready for end users until it is cut and released.  Dan - am I right?
>

Speaking as ESI-the-vendor, we agree completely with the idea of
getting the documentation out earlier, including before the docs and
the features described are complete.  As Chris notes indirectly, GPLS
had us work this way on this particular project, and I think we've all
(ESI, GPLS and the community) learned positively and negatively from
the process.

We've been discussing internally the how's and wherefore's a bit today
and are developing an ESI process (and will be sharing said, so that
others may suggest improvements or duplicate good ideas) that we
believe will accomplish the goals expressed on this thread without
letting in-process documentation fall into committee-itis traps.  More
on the specifics of that later, and from others than me, most likely,
but I thought it important to make sure it's understood that ESI
doesn't want to foster any sort of environment where commissioned work
leads to a "vendors vs users" feeling.  We're all, individually and as
a company, committed to being just like any other community members;
that has always been our aim.

-- 
Mike Rylander
 | VP, Research and Design
 | Equinox Software, Inc. / Your Library's Guide to Open Source
 | phone:  1-877-OPEN-ILS (673-6457)
 | email:  miker at esilibrary.com
 | web:  http://www.esilibrary.com