TOCs within one document can guide users to the appropriate sections while allowing searching within the larger document. Users/System Admins/Developers would seem to be logical sections w/ each having a TOC under that. Just my thoughts.
robin On Mon, Feb 8, 2010 at 4:18 PM, Dan Scott <[email protected]> wrote: > 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 > -- http://contentdivergent.blogspot.com
_______________________________________________ OPEN-ILS-DOCUMENTATION mailing list [email protected] http://list.georgialibraries.org/mailman/listinfo/open-ils-documentation
