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

[Mike Rylander]

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