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

[Daniluk, Judy]

The sections of the staff client called "Local System Administration"
and "Server Settings" might merit their own chapter.  Most users won't
venture there very often, but these features don't require the same
level of access as real System Administration.

 

Judy Daniluk

Technology Consultant, North Texas Regional Library System

jdaniluk at ntrls.org     817-201-6778(cell)    

 

From: open-ils-documentation-bounces at list.georgialibraries.org
[mailto:open-ils-documentation-bounces at list.georgialibraries.org] On
Behalf Of web gurl
Sent: Monday, February 08, 2010 3:32 PM
To: Documentation discussion for Evergreen software
Subject: Re: [OPEN-ILS-DOCUMENTATION] Book of Evergreen: suggestion
foradditional chapter

 

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/99cbbb05/attachment.htm