RE: Odd problem with open-ldap

["Pierangelo Masarati" <ando@sys-net.it>]

Daniel,

> Well then put them in as examples.
>
> I really don't understand the huge resistance here to putting examples
> into the documentation.

There's plenty.

>
> Knowing WHAT variables/parameters, etc need to be twiddled is more than
> half of the battle.  This may apply more to the BDB configuration details
> than the installation ones, but it's the same issue, and met with the
same argument.

How deep should we go into details?  DO you enjoy the type of docs that
start with: plug your desktop; switch it on; if it doesn't switch on check
that the power supply is working".  Should we define what a "shell" is? 
What an "editor" is?  What a "compiler" is?  What the "internet" is, to
instruct people on downloading the sources?  I think I made the point.

>
> So what if it is impossible to create an example that is "correct" for a
> particular hardware/software environment.  Label the example clearly so
> that people know what it is intended for.  At least then there would be a
> starting point.
>
> Here is the main theme of the support side of this mailing list:
>
> Q:  I have a bug in X.X.X ancient version of openLDAP that came from
> random binary foo.
> A:  Upgrade to the latest version - build from source.

Other than "gimme console access as root to your box and I'll try to fix
it", I don't see anything else one could do.  Newer versions are released
__exactly__ to fix problems people had with older versions, not just for
fun.

>
> Q:  I (like 50 other people this year) am having problem X building from
> source.  What's wrong?
> A:  You're an idiot who doesn't know how to build software.  Search the
> list, and see if anyone answered another idiot like you before.

Nobody ever says this (people would be banned from the list).  However, I
bet at least 49 of these 50 people could have their problem solved out of
the FAQ, but they didn't look there.

>
> Q:  Obviously, I'm not an expert of this platform, this is why I was using
> a binary install before.  Where is there a guide on building the software
> on common platform X?
> A:  Search the list.

I'd rather send you to the FAQ, which is a bit more authoritative.  Let me
repeat the sequence:
- the man pages/admin guide
- the FAQ
- the mailing list
- google

>
> Q:  After finding a non-official guide on XYZ website, I finally got it to
> install.  Now the performance sucks with BDB.  What's wrong?
> A:  You shouldn't rely on non-official documentation - its probably not
> correct for your exact platform and use case.

This answer is simply perfect, I wouldn't change a bit of it.

>
> Q:  Fine, whatever.  It installed and passed its own tests.  But why is it
> so slow?
> A:  You need to configure BDB.  Search the list.

It's in BDB's docs __and__ in the FAQ.

>
> Q:  So I always have to create a file DB_CONFIG, what should I set the
> variables x and y to?
> A:  Depends on your environment.  And set z as well.

It's in BDB's docs __and__ in the FAQ

>
> Q:  To what?  50?  50000?
> A:  Depends.

It's in BDB's docs __and__ in the FAQ.  There's even an algorithm to
compute the exact value, if you can't give it a guess...

>
> Etc.  But I guess I live in that alternate world where we look at the
> common problems users have, and try to fix the software and/or
> documentation so that they don't occur.

The docs are there, if you agree on calling the FAQ "docs".  I do, and I
do my best to add to it every piece of knowledge I gather on using
OpenLDAP - I recall the FAQ is interactive and, besides being an OpenLDAP
developer, my FAQ account by no means differs from the one you could
create for yourself in 2 secs.  The FAQ is often built out of good
postings to the mailing list, and good FAQ entries eventually make it into
the man pages and the admin guide.  Common problems should be listed there
by people who ran into them and eventually got them fixed.  Somebody
replies that the FAQ sucks.  Thanks a lot, I think that's a terrific cool
excuse not to use/improve it.

>From your posting, it is my understanding that what you're thinking of is
customized support, not docs.  More than 99% of what people need is
already out there; only, it may be difficult to find, because there's too
much, and part of it is unsorted.  Customized support, on the contrary, is
already there, and it's called patient people reading the mailing list, or
commercial support.  Guess what's easier and cheaper to ask for.  When I'm
in a good mood, or idling, I can spend 2 minutes in digging out the right
FAQ entry for some "idiot" (you used it first), but this can't be a full
time job (especially for free).

p.

-- 
Pierangelo Masarati
mailto:pierangelo.masarati@sys-net.it


    SysNet - via Dossi,8 27100 Pavia Tel: +390382573859 Fax: +390382476497