[OPEN-ILS-DOCUMENTATION] Documentation session pre-work: hierarchy ideas

[Karen Collier]

Karen S,

It looks like you've done a good job of categorizing the various topics that need addressing in the documentation.  It occurs to me though, that there's another facet that might merit consideration for the top level of the hierarchy.  I'm thinking audience.  We have at least 3, maybe 4 audiences within the community that would be using the documentation.  Decision/Policy Makers, Technical Staff, and Front Line Staff.  The possible 4th I'm thinking of is Library Patron/Customer.  

The advantage of making audience the top level in our hierarchy would be that Policy Makers and Front Line staff don't feel they're missing anything they'll need by skipping the scary technical stuff.  And the technical parts could be written a little more technical than if it was meant for a general audience, and the only available source of info on certain topics.  Cross references and a shared index could help bring together the audience-based volumes/sections where topics are of interest to more than one audience.  And of course, if someone wears more than one hat, they could read everything applicable to them.

The downside I see is that where there are overlapping topics, we may wind up with documentation on a single topic scattered in different places like we have in the wiki.  On the other hand, cross references could help address this potential problem, and it could be an upside in some cases.  For example, on customizing Evergreen, Policy Makers would like to know what their options are, but not necessarily all the nitty gritty on how they'd be implemented, particularly if implementation requires technical magic outside the staff client.  Their section could address customization options, with cross-references to the appropriate parts of the Technical Staff section that explain implementing those options.

Anyway, it seems to me there's more than one right answer to choose from.  Just tossing this out there for consideration.  :)

Karen C

----- "Karen Schneider" <kgs at esilibrary.com> wrote:

> Hi folks, in preparation for the documentation discussion next week
> at
> the Evergreen conference, I've been looking at documentation projects
> and also at earlier efforts we've done in our own community.
> 
> I've based the following possible hierarchy for Evergreen
> documentation on Dan Scott's initial proposed hierarchy (see
> http://svn.open-ils.org/trac/ILS/browser/trunk/docs/index.xml ). Note
> that in a lot of projects the actual content is broken down into
> small
> chunks of XML (or other formats) so that documentation activities can
> be distributed among a large group of writer/editors. I believe that
> the idea of providing one file was to give us something to start with
> so we could think through the hierarchy issues.
> 
> What do you think? In terms of top-level hierarchies, what would you
> change, move, or add? Would you see this collated as one large book
> (how PostgreSQL does their documentation) or in several books (as
> several other projects organize their docs)?
> 
> ---------------
> 
> Book of Evergreen -- Sky-high view -- think piece
> 
> *Index.xml
> 
> -Introduction to Evergreen
> -Installing Evergreen
> -Administering Evergreen
> -Staff Services
> -Customizing Evergreen
> -Technical Reference
> -Guides and Glossaries
> -Frequently Asked Questions
> -Community Documentation
> 
> 
> ----------
> 
> Book of Evergreen Hierarchy think piece, Partially Expanded
> 
> -Introduction to Evergreen
> --What is Evergreen?
> --A brief history of Evergreen
> --Technical architecture
> --Evergreen concepts
> --Bug reporting guidelines
> 
> -Installing Evergreen
> 
> --Setting up the router
> --Setting up PostgreSQL
> --Setting up memcached Servers
> --Configuring Evergreen
> --Configuring Apache web server
> --Installing the Evergreen staff client
> --Upgrading Evergreen
> --Common problems with Evergreen installations
> 
> -Administering Evergreen
> 
> --Starting and stopping Evergreen services
> --Setting up organizational units
> --Generating reports
> --Preventing disaster
> 
> -Staff Services
> 
> --Acquisitions
> --Cataloging
> --Circulation
> --LocalAdmin
> --OPAC
> --Reports
> --Reserves
> --Serials
> 
> -Customizing Evergreen
> --Customing the staff client
> --Changing labels and messages
> --Changing key mappings
> --Customizing the catalog
> 
> -Technical Reference
> 
> --Application programming interfaces (APIs)
> --Web services
> --Database schemas
> --Communication protocols
> --Configuration files
> 
> -Guides and Glossaries
> 
> -Frequently Asked Questions
> 
> -Community Documentation
> 
> 
> -- 
> -- 
> | Karen G. Schneider
> | Community Librarian
> | Equinox Software Inc. "The Evergreen Experts"
> | Toll-free: 1.877.Open.ILS (1.877.673.6457) x712
> | kgs at esilibrary.com
> | Web: http://www.esilibrary.com
> | Be a part of the Evergreen International Conference, May 20-22,
> 2009!
> | http://www.lyrasis.org/evergreen
> _______________________________________________
> OPEN-ILS-DOCUMENTATION mailing list
> OPEN-ILS-DOCUMENTATION at list.georgialibraries.org
> http://list.georgialibraries.org/mailman/listinfo/open-ils-documentation

-- 
Karen Collier
Public Services Librarian
Kent County Public Library
408 High Street
Chestertown, MD 21620
410-778-3636