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

[Karen Schneider]

Not to scare you all by exhuming 100-day-old messages and picking up
discussion as if it were yesterday ;-) but I was working on the Evergreen
style guide today and took another look at our earlier discussions about
hierarchy. It's my take, a few months later, it doesn't really fit our needs
-- too much is squashed into "staff services," for example.

I'm thinking two parallel books (joined in a volume) could work this way:

Installing
Upgrading
Migrating from other ILSs
System administration
Software developers' reference
Web developers' reference

Local administration
The OPAC
Cataloging
circulation
Reports
Acquisitions

Thoughts? The primary reason to think ahead about structure is it does
affect what tags you have at your disposal (and the styling, too).

-- 
-- 
| 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


On Mon, May 11, 2009 at 7:46 AM, 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
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://list.georgialibraries.org/pipermail/open-ils-documentation/attachments/20090826/01b68061/attachment.htm