[OPEN-ILS-GENERAL] Writing an Evergreen manual

[Dan Scott]

On 10/10/2007, Karen Collier <kcollier at kent.lib.md.us> wrote:
> Dan,
>
> I love the idea.  I think it'll really help to promote Evergreen within
> libraries that might be sitting on the fence to have a carefully organized
> and comprehensive document like you're describing, explaining Evergreen's
> strengths, why one would want to migrate, as well as overviews of the server
> setup and migration process, administration, and day to day usage of the
> staff client and OPAC.  I'd also like to help to the extent that I can.

Awesome! The more the merrier!

> I have a couple of comments on the testbook you set up.  First, it could be
> my computer with the issues, but I'm seeing funny characters in the
> headings.  For example "Chapter[funny_character] 1.[funny_character] Why
> read this book?" where funny_character looks like a capital A with a hat.
> Any idea what's causing this?

Yup, that's an Apache server configuration issue; the content of the
XHTML output from the manual is in UTF-8, but the open-ils.org Apache
server is issuing a content-type header specifying a charset of
iso-8859-1 (and by the magic of charset encoding resolution, the
header wins out over the charset declaration in the document itself).
I mentioned it to Brad a few nights ago, so hopefully he can poke at
the config a bit and remove the pure evil "AddDefaultCharset On"
setting from the Apache config.

> Secondly, I like the literary reference in "A Tale of Two Evergreen Systems"
> but I'm not sure those two examples are fully inclusive.  My library system
> is a small rural public library that is not yet a consortium.  We may in the
> future want to bring our county's school libraries' collections into the
> catalog or merge catalogs with our neighboring systems, and like the idea of
> being prepared for that future possibility, which is part of why we like
> Evergreen.  There are also a lot of other features of Evergreen that appeal
> to a small library such as ourselves, even if we won't necessarily use the
> full extent of its features.

Feel free to contribute a third scenario, or to differentiate the
existing scenarios in a way that does a better job of capturing
different requirements and potential server/software configuration
scenarios - I originally dashed those scenarios off literally in less
than ten minutes, and haven't touched them since, so more care in
refining them before we go forward with documentation based on the
scenarios would be great! I was just hoping to get the seed of the
idea of scenario-based, grounded documentation planted :)

> Hi Sally et al:
>
> I apologize to everyone for getting people excited about this, and then
> about not making much progress beyond checking the skeleton table of
> contents into the Subversion repository. I was trying to get a nightly build
> of the documentation in PDF and XHTML set up on open-ils.org but it's been
> slow going. Since Thursday I've been in transit and on vacation, taking a
> needed break from the computer, but plan to get back in the swing of things
> this week if the Access conference schedule allows me to.
>
> A few quick responses:
>
>   * I don't expect everyone to contribute in DocBook format. I've mentioned
> this in response to a few private inquiries about contributing, but as far
> as I'm concerned I'm interested in well-written accurate documentation -
> format be damned. If it's a useful addition to the manual, you can hand it
> to me on a paper towel and I'll do the work of converting it over to
> DocBook. Of course, over time having more DocBook-savvy people will
> certainly help the documentation project, but in the short term I'm happy to
> do the relatively light lifting of converting to DocBook format. I'm worried
> more about maintaining a consistent voice and style than I am about
> consistent markup - the reason I wrote up two rough scenarios for libraries
> deploying Evergreen was because I would like to have each section touch on
> those scenarios and what differs depending on the scenario.
>
>   * DocBook certainly can handle graphics and illustrations to go along with
> text.
>
>   * The original template is in the Evergreen Subversion repository at
> http://svn.open-ils.org/trac/ILS/browser/trunk/docs/index.xml - my rough
> plan is to break this up into separate files over time and flesh out
> chapters so that they can be used as templates.
>
> Sally, please feel free to add some more information to the wiki, as you
> suggested! I'm happy to have others carry the ball for this project too.
>
> --
> Dan Scott
> Laurentian University
>
>
>
>


-- 
Dan Scott
Laurentian University