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

[Karen Schneider]

>
> 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. ;-)

Actually in DocBook some of these decisions may be key -- because in
addition to markup, DocBook supports some very interesting
functionalities with respect to glossaries and glossary terms.
Glossaries can be generated dynamically from glossterms and firstterm
elements used in the documents. (See Chapter 17 of Bob Stayton's
DocBook XSL: The Complete Guide.) I don't know how much separating
content into separate books might (if at all) hinder the compilation
of glossaries (or aid the effort, if the idea is to create
context-appropriate glossaries).

Glossaries can also be formatted manually, though even if that's how
things begin, there are obvious advantages to using glossary markup in
the glossary as well as in the documentation.

Sorry, I've been reading up far too much on this stuff :-)


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