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

[web gurl]

Hi Karen,
Just a few random thoughts and questions as I consider the possibilities.
;-)

I think your proposed hierarchy looks good. The vocabulary choices and
organization seem logical to me.

How would this hierarchy accommodate future changes
(additions/deletions/revisions?) For example, where would a list of ALL out
of the box assigned/shortcut keys fit? Would it be included under
-Customizing Evergreen  --Changing key mappings (in whatever documentation
resides there) or would it fit into one of general resources listed towards
the end?

Also, are you envisioning more of a parent/child relationship as with a
taxonomy (as I am sensing)?

I like putting the 'FAQs' and 'Guides and Glossaries' in a separate section
(quick and ready reference!) but I would hope that the actual documentation
would also cross reference/make reference to those materials. I could just
see where useful info might be overlooked if a user only went to "their"
section of the book. Of course, those are really documentation issues, not
hierarchical issues. ;-)

Following on that, in terms of collating the book, I believe that it will be
easier to manage if it is chunked up into several books with those books
having some sort of linkage/relationship, of course.

Just my somewhat random thoughts. ;-)
Thanks,
Robin
robinfay.net

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
> _______________________________________________
> 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/20090511/4cb1d70c/attachment.htm