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

[Karen Schneider]

On Fri, May 15, 2009 at 9:17 AM, Karen Collier <kcollier at kent.lib.md.us>wrote:

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



True! Though we both have ignored probably the most fundamental root of any
documentation hierarchy... RELEASE.


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



There are actually implied audience levels in this first "rough," though
they may not be adequate. "Staff Services" (at least in my head) comprises
those manuals we see developed by and for librarians, documenting the
function of the modules (circ, opac, reports, cataloging, local admin, acq,
etc.). The other sections are more technical. FAQs could be of any flavor.
Community documentation -- again, this is all in my imagination, take it
with a grain of salt -- could be all those contributions developed by
Evergreen projects that the documentation central committee (which, note,
does not yet exist) has not pulled into the central project.

In fact in terms of book design I went back and forth my first proposed
structure with the idea of having three distinct sets of documentation. (So
to express it in DocBook, the structure would be
set/books/chapters/sections.) Unstyled HTML with no pictures for
programmers, of course, and well-styled CSS-ified HTML with lots of images
for the rest of us. ;) Seriously I actually wondered if something as simple
as style could be used to help distinguish among audiences, or if styling
could help address different needs.

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



Absolutely! When it comes to organization there are various models to
follow. I keep looking for projects that are similar to ours that have very
well-developed documentation sets. One problem with most of the projects is
that they are tools used by and for highly technical folks, and their
documentation reflects that. We really need more documentation examples. If
anyone has any, do share!


-- 
-- 
| 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/20090515/1b63b084/attachment.htm