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. _______________________________________________ OPEN-ILS-DOCUMENTATION mailing list [email protected] http://list.georgialibraries.org/mailman/listinfo/open-ils-documentation
