[imp] IMP LDAP warnings

[Per Bothner]

Jon Parise wrote:
> It is difficult for us to assemble documentation that describes how to
> set up all of the services that Horde / IMP might possibly use (e.g.
> Apache, PHP, MySQL, PostgreSQL, Oracle, OpenLDAP, Cyrus, UW-IMAP, just
> to name a few of the "common" pieces of software).

It is difficult, but necessary.  It may make it easier to replace
docs/INSTALL by online html pages.  You could have a page for using
Oracle, a page for using OpenLDAP, etc.  Initially, they can just
say "HELP - if you succeeded in using Horde with XXX, please email YYY
and tell us how you did it, so we can decsribe it here."

Of course you want to be as specific as you can about which versions
of software the intructions have been tested with.

> The FAQ (http://www.horde.org/faq/) covers those kinds of issues
> rather well.

Yes, but finding the right FAQ section may require some hunting.
If your test page can determine a problem why not just display
a link to a web page that suggests a fix?

More generally, perhaps you can turn these test pages into a
installation and configuration interface.  Of course the many
options and configurations and dependencies make that difficult,
but you do have a nice GUI interface for user configuration -
can you develop something similar for installation and system
configuration? (SInce people tend not to read documentation until
they have to, it is always prefereable to make things self-documenting.)

> I apologize for being so blunt, but we're often criticized for
> "lacking" documentation.

"What I tell you three times is true."

> When one considers that there are only a few
> of us here developing the project, and none of us are primarily
> documentation writers, I think what we have is pretty good.

There is only one of me developing Kawa, and I'm not primarily
a documentation writer.  Kawa documentation isn't great either, and
I don't have quite as many complicated dependencies - but I have some.
But a lack of people why a "primarily" writers is just an excuse.
Writing documentation is a matter of practice, and most tech writers
aren't going to be able to puzzle out the installation unless you
show them.  So instead of telling them, just write it down.  And
then read it over and try to make it as complete and comprehensible
as you can.

Sorry to rant and point out the obvious, but it would be a shame if a
great application like Horde/IMP fails to catch on because it is too
difficult to install.
-- 
	--Per Bothner
per@bothner.com   http://www.bothner.com/per/