[OPEN-ILS-DOCUMENTATION] Re: [OPEN-ILS-DEV] Evergreen installation problems

[Dan Scott]

On 14/02/2008, Deb Bergeron <bergeron at macalester.edu> wrote:
>
>  Jason, Dan, et al,
>
> Could we work on developing documentation for the install and create a CD
> as part of the documentation project?  It seems this is a HUGE issue or am I
> simply misguided here?
>
> Thoughts?
>
> Deb
>

Putting this back on the -dev list as well, as it is very relevant to the
discussion at hand.

I know one of the other members of the doc team has already expressed
interest in improving the install documentation. Please don't let what I'm
about to say dissuade you from having a go at the install docs, if you have
some ideas about how it could be improved! But...

Having personally put a ton of effort into the existing install
documentation on the wiki, I'm not in favour of putting much more work into
the install documentation - it is the area most subject to change (due to
new or dropped requirements) and the area that currently requires the most
variety of skills from the users (compiling various libraries, configuring
Apache, configuring ejabberd, and configuring Evergreen itself - along with
knowing how to debug all of this when something goes wrong). Some of it is
incredibly painful to debug because the packages we depend on don't provide
helpful error messages (ejabberd's "RPC node down" can mean any number of
problems).

There are times when documentation simply can't make up for inherent
complexity. A former colleague of mine said "If the interface is a dog, the
help will bark." I don't think the install and configure process for
Evergreen is a dog: we're talking about installing an application built on a
complex service-oriented architecture, so some difficulty has to be
anticipated... but we've been trying to incrementally improve the
out-of-the-box install and configure process, starting with the elimination
of one mostly redundant configuration file back in the spring and continuing
with better defaults for library linking, compile flags, etc - basically
removing as many manual steps as possible. Mike has added the ability to
bypass all of the fully-qualified domain name and simply use "localhost" for
a single-server install. Some of this is sitting in trunk and simply isn't
visible yet.

I believe that further effort would be better spent on converting the build
& install process to using autoconf / automake, and then eventually building
distribution-specific binary packages - but the current Evergreen
development team simply doesn't have those skills today, and are focusing on
other development priorities (acquisitions, anyone?) rather than building
those skills in-house. We would _love_ for somebody to pitch in on improving
the build and install process. If you have skills in GUI design, maybe
another nice-to-have would be a unified view of all of the configuration
settings in a pretty GUI with associated help and validation. Crazy idea,
maybe.

The one install and configure area that people seem to get the most tripped
up on is Jabber configuration, with Jabber's domains and users making things
hard to document clearly in a step-by-step fashion. I think it would be
worthwhile to invest some time in providing a clear conceptual overview of
how the Jabber users interoperate, which user needs to be specified in which
section of opensrf_core.xml. Maybe a "debugging ejabberd howto" would be
useful, too. If you have a working Evergreen install, deliberately break
your ejabberd configuration and document the resulting symptoms of that
breakage (which log files would you find the problem in? what error messages
do you get?), along with the solution. Repeat for every variation of
breakage that you can think of - that would probably go a long way towards
helping some of the configuration problems that are pretty much out of our
control (short of sponsoring an ejabberd developer to add defensive
programming and meaningful error messages to ejabberd itself).

That being said: if you run into a problem getting Evergreen running and you
contact us on IRC (#OpenILS-Evergreen on Freenode or http://open-ils.org/irc)
or send the list an email, we do try our best to help out. Talk to us early,
rather than letting frustration build up. If you're using a distribution
that doesn't have install instructions written for it, then unfortunately
some pain is probably going to be associated with that. If you work your way
through a problem that hasn't been documented or gain insight on how some
pieces fit together that weren't clear before or successfully install a new
distribution (with or without our help - OS X people, I'm talking to you,
too!), it would be really nice to have your hard-won knowledge shared with
the rest of the community - send an email to the list, or add it to the
wiki. Maybe that will spark an idea about how we can simplify another part
of the install and configure process so that everyone can benefit.

Just my opinion.

-- 
Dan Scott
Laurentian University
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://list.georgialibraries.org/pipermail/open-ils-documentation/attachments/20080214/2951dc2c/attachment.html