[OPEN-ILS-DOCUMENTATION] How and what should a "vendor" document? WAS: 2.1 Status and Blocking Bugs Request

[Lori Bowen Ayre]

Mike,

Could you explain what the difference between "feature documentation" (which
you don't provide) and the documentation you provide as part of your
development work?

Lori


On Thu, Sep 1, 2011 at 7:52 AM, Mike Rylander <mrylander at gmail.com> wrote:

> A little off topic, but ...
>
> On Thu, Sep 1, 2011 at 9:46 AM, Soulliere, Robert
> <robert.soulliere at mohawkcollege.ca> wrote:
> > Michael brings up some excellent points.
> >
> > In regards to his first point regarding upgrade instructions, I wonder if
> the basic upgrade instructions (from last version of previous major
> release?) could be made part of the README or install text files just like
> the clean install directions. The wiki and DocBook versions could then pull
> the instructions from this authoritative source which is coupled with the
> code at release time. Could this address your first concern Michael? Would
> this is possible for the release team?
> >
>
> I can't speak to the disposition of the DocBook version, but given an
> initial translation of the upgrade instructions to asciidoc to be
> embedded in the README or a separate UPGRADING file, in the
> repository, it wouldn't seem particularly more burdensome to pull
> together an upgrading wiki page from that.  IMO, anyway.
>
> > In regards to the second point regarding new features: This came up for a
> bit of discussion at the DIG meeting at the last Evergreen conference and I
> think was also discussed on a different list. One point was made that the
> support vendors and customers negotiate supporting documentation being
> developed for the customer and sharing with the community. I am not sure
> about this exact process in regards to vendor customer discussions, but I
> would suggest that documentation for new features be discussed with your
> vendor if you are sponsoring the development.
>
> FWIW, building in time for documentation is now (and has been for a
> while now) a standard part of ESI's development contracts, because
> it's often as important to the end user as having the code in place --
> IOW, it's an assumed part of our development proposals.  We deliver
> the documentation at the end of the project, so that we capture any
> changes the occur during the testing and acceptance process.  After
> delivery to a client, we then send it to DIG for incorporation with
> the official docs.  It works well for us, as it makes sure that the
> features we create get documented, and I'd encourage other vendors
> (including those internal to an organization, not just "outside" firms
> like ESI) to design documentation into their development process as
> well.
>
> We don't, however, build feature documentation time into consulting
> projects, as documentation time can equal or exceed "technical
> services" (data munging, development, configuration, etc) time.  We do
> offer it, just not as an assumed part of consulting.  That's something
> that I'll bring up internally, and I'd be interested in the rest of
> the communities thoughts on that topic
>
> --
> Mike Rylander
>  | Director of Research and Development
>  | 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
> _______________________________________________
> OPEN-ILS-DOCUMENTATION mailing list
> OPEN-ILS-DOCUMENTATION at list.georgialibraries.org
> http://list.georgialibraries.org/mailman/listinfo/open-ils-documentation
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://list.georgialibraries.org/pipermail/open-ils-documentation/attachments/20110902/5068e515/attachment.htm>