SPAM: Re: [OPEN-ILS-GENERAL] Writing an Evergreen manual

[Dan Scott]

On 25/09/2007, Murphy, Sally <smurphy at georgialibraries.org> wrote:
>
> I'm also all for this idea, not only for version control (which is certainly
> a good thing), but also because I find a manual easier to use than the wiki.
>
> I'll be happy to contribute by writing a section and/or prettying up stuff
> from the wiki – I've already been compilling everything I can find on
> OpenSRF (from various blog posts and the like), so organizing that into a
> single document might be a good place for me start.

Awesome! I could see this acting as a standalone document for the
OpenSRF project (which is taking flight as a project on its own), as
well as integrating it into the reference section of an Evergreen
manual.

> I could also work on some of the "Core Tasks" section, if the outline on the
> demo below is the one you want to stick with – I'd suggest adding a
> "troubleshooting" section, too, for things like "Receipts only partially
> printing" and "xulrunner crashing" and the like – I can also add to that as
> I learn more about fixing the software.

A troubleshooting section would be a good addition, definitely. One
troubleshooting section per chapter, perhaps, to keep the
troubleshooting info close to the subject matter?

> What would be *really* nice would be if we could also put the parts of the
> manual that concern the staff client into a Help file that could be packaged
> with it.  Especially for the troubleshooting section.

Absolutely. The good news is that this should be pretty trivial to
accomplish; I've created online help bundles for Eclipse in the past,
and the XUL online help packs are pretty similar in structure -
basically a set of XHTML files, with a few RDF files that express the
table of contents / index / package structure. Wire up a shortcut-key
to "Help" (although the world-standard of F1 for help is already
taken... grrr!), map each dialog window to a particular XHTML file,
and we're there!

I'll hopefully have a good framework for the basic XHTML + PDF up and
running by the end of the week, if all goes well.

-- 
Dan Scott
Laurentian University