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

[web gurl]

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 <dan at coffeecode.net> 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
> OPEN-ILS-DOCUMENTATION at list.georgialibraries.org
> http://list.georgialibraries.org/mailman/listinfo/open-ils-documentation
>



-- 
http://contentdivergent.blogspot.com
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://list.georgialibraries.org/pipermail/open-ils-documentation/attachments/20100208/8c1b73cc/attachment.htm