[OPEN-ILS-GENERAL] Writing an Evergreen manual

[Dan Scott]

On 09/10/2007, Murphy, Sally <smurphy at georgialibraries.org> wrote:
>
>
>
>
> Hi, all -
>
>
>
> I haven't heard much about the EG manual in a while, but some decent static
> documentation for this project is really needed, particularly for end-users
> (i.e., library staff), so here's an email to get it back on everyone's mind.
> =)
>
>
>
> I see that something has been added to the Wiki on the website concerning
> the manual, however, the information there isn't particularly useful for
> potential contributors.  May I suggest that we include instructions for
> submitting sections.  By instructions, I mean something like:
>
>  "If you would like to contribute documentation to the EG manual, send your
> submission as XML files in the docbook format to the Open-ILS Dev listserv
> with "EG Manual Submission: <short description>" in the subject heading.  If
> your submission includes more than one file, please compress them, in the
> proper file-structure."
>
>
>
> Also, I, could use some example XML – I have no interest in writing out a
> manual in XML; I've been using OpenOffice and Excel for QA documentation,
> which will be the starting point for my EG manual submissions.  A template
> or an example would be really useful for me to port over some of that
> information, and I'm sure other potential contributors would find some
> templates useful.  I suggest that the original example skeleton sent to this
> list be linked or uploaded, or turned into some templates (like chapter
> template).
>
>
>
> Also, what kind of support does doc books have for graphics, and formatting
> pages with them?  Focusing on end-user stuff, there will be lots of
> screenshots, diagrams of menus, pictures of icons, and such.  I'm sure
> docbooks must support this kind of thing, but haven't really had the time to
> delve into looking for that information.  If anyone out there knows more
> about this than me, it might be nice to just put some of that information
> here on the list, or, better yet, on the wiki in the section on the EG
> manual.
>
>
>
> Just some thoughts
>
> -Murphy
>
>
>
> (GPLS QA for Evergreen)
>
> Some say the world will end in fire and ice.  Others say it will be
> segfaults.
>
>
>
> -----Original Message-----
>  From: open-ils-general-bounces at list.georgialibraries.org
> [mailto:open-ils-general-bounces at list.georgialibraries.org]
> On Behalf Of Etheridge, Jason - Gmail
>  Sent: Tuesday, September 25, 2007 1:38 PM
>  To: open-ils-general at list.georgialibraries.org
>  Subject: Re: SPAM: Re: [OPEN-ILS-GENERAL] Writing an Evergreen manual
>
>
>
> On 9/25/07, Dan Scott <denials at gmail.com> wrote:
>
> > Wire up a shortcut-keyto "Help" (although the world-standard of F1 for
> help is
>
> > already taken... grrr!),
>
>
>
> Oops. :-)   Suggestions welcome.
>
>
>
> --
>
> Jason Etheridge
>
>  | VP, Community Support and Advocacy
>
>  | Equinox Software, Inc. / The Evergreen Experts
>
>  | phone:  1-877-OPEN-ILS (673-6457)
>
>  | email:  jason at esilibrary.com
>
>  | web:  http://www.esilibrary.com
>
>

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