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 > [email protected] > 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 > [email protected] > http://list.georgialibraries.org/mailman/listinfo/open-ils-documentation -- Grace Dunbar COO Equinox Software, Inc. [email protected] 1-877-OPEN-ILS x5579 www.esilibrary.com _______________________________________________ OPEN-ILS-DOCUMENTATION mailing list [email protected] http://list.georgialibraries.org/mailman/listinfo/open-ils-documentation
