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 <[email protected]> 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 > | [email protected] > | 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 > [email protected] > http://list.georgialibraries.org/mailman/listinfo/open-ils-documentation > -- http://contentdivergent.blogspot.com
_______________________________________________ OPEN-ILS-DOCUMENTATION mailing list [email protected] http://list.georgialibraries.org/mailman/listinfo/open-ils-documentation
