[OPEN-ILS-DOCUMENTATION] Book of Evergreen: suggestion for additional chapter

[Dan Scott]

On Mon, 2010-02-08 at 08:13 -0500, Steve Wills wrote:
> I rather agree with Joe that the idea of a Systems Integration manual for EG is necessarily technical.
> 
> I would suggest that DIG generate a Users Manual and System Integration Manual as separate documents.
> If I was going whole hog, I'd point out that most systems that are this complex actually target three groups separately.
> 
> Users Guide
> System Administrators
> Developers
> 
> These three groups generally have different interests and areas of expertise.  Try to speak to all three audiences in a single
> document has the potential of not speaking to any of them.

Hmm - on the other hand, if you search for "self-check" or "SIP" in the
separated-out User Guide and get no hits, you might assume that there is
no support for it in Evergreen. If you search for it in an all-in-one
manual and you get hits, but they're deeply technical, then you can at
least hand it off to your deeply technical person (if you have one). A
common mistake in these sorts of divisions of content is to hide
complexity from the user in the user guide, which leads to a perception
that things only work in the way that they come out of the box - and
then the system administration docs give you terse descriptions of the
various configuration variables that can be tweaked without giving a
user's eye view of how those changes affect the user experience.

Remember that coming from DocBook, you should be able to produce a PDF
version of the documentation, a Web version of the documentation, an
epub version of the documentation... all with the appropriate links from
section to section. It would be weird for the Web version to deliver a
User Guide that only links to topics within the User Guide, rather than
to its natural counterparts in the Sys Admin and Developer sections. If
you're in the User Guide and you're reading up on how holds work, you're
going to want to know that there are hard boundaries and soft boundaries
that determine how far a given hold transits; and you'll want a link
from the pertinent section in the User Guide on holds to the System
Administration section that tells you or your systems administrator (if
you're lucky enough to have one) how to set holds up to work the way you
want. I think it's still a lot easier to create intra-document links
within a single document than across three separate documents.

I would suggest worrying about splitting out the content into separate
documents much, much later in the process, say after that content has
actually been written. After the content has been written, there's
nothing to stop you from creating both an all-in-one view of the
documentation and separate manuals from a single set of source
materials.