Re: Answering frequently asked questions

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

> fre, 19.12.2003 kl. 02.43 skrev Ace Suares:
>
>> I don't like the faq. It's structure does not lead people to the right
>> place  very easy. That's because if you start in, you have no idea in
>> what category  your answer will be. A traditional faq is much more
>> searchable. Maybe a  wikiwiki might be usefull, I don't know.
>>
>> If ever I send something to the list that others consider usefull,
>> please add  it to the FAQ because I won't. I never use the FAQ (unless
>> someone sends me a  link straight to the article or google shows me
>> how to go there).
>>
>> I don't want to be negative, but the FAQ s*cks. Especially for ACL's.
>
> I find myself agreeing with Ace, right up to the dots on the eyes and
> the crosses on the tees, yet again. It didn't use to be that way. Hey,
> Ace, what's up man?
>
> I know there's been a lot of work done on the FAQ, mostly by Kurt.
> Perhaps an index or search mechanism might help - don't know whether
> that's possible with Faq-O-Matic. I still get the best answers to
> questions by searching through the list postings on my harddisk
> (severely curtailed by my having wiped out everything before May last).
>
> As for contributing to the FAQ, I did once and a person who shall be
> nameless rapped me so hard over the knuckles in a private mail, that I
> shall take good care before ever doing so again.
>
> I agree with Ace that especially ACLs should be given their own
> document/man page. Pierangelo's and Kurt's recent ACL suggestions in
> postings have left me breathless - the worst thing is, that both assumed
> that mortals should know what they were talking about - or where it was
> documented (*DO NOT REFER TO 'man(5) slapd.access', 'man(5) slapd.conf'
> or the Admin html doc*). Since both are main authors of the Openldap
> suite, it would be reasonable for both to understand what they were
> talking about. And no, I can't contribute to docs, because I don't know
> what they were talking about.
>
> I'm full of admiration for Openldap, the power users on this list and a
> huge protagonist of them all, don't get me wrong.

Thanks for the compliments (I'm taking your comments as such)

Whenever I apply some changes to OpenLDAP I try to keep the man
pages aligned with it.  Of course there might be some delay
between the moment I apply the changes and the moment they get
released.  You might hear rumors about some recent changes on the
-devel list, and then see them in a release weeks or months later
(or never, if they never get to release state), or you may never
see them because you don't ever look at slapd.access(5) (you did
it a month ago and it never changes so why sould you look at it
again?) (Kurt, maybe we should add man page changes to the CHANGES
file, so nobody will be allowed to complain about doc changes not
being logged timely).

AFAIK the Admin guide usually lags a bit behind the man pages,
because it is meant to be a comprehensive guide to configuring,
administering and using OpenLDAP software, so punctual changes
cannot fit in it until they're part of a more general view.

As a user, sometimes I complain about manuals not being up-to-date,
but as a (n Open Source) developer, I understand quite well that
the (current version of the) code is the only reliable source
of information about its usage.

That's what I did, a couple of days ago, to write the access
requirements for each operation in slap.access(5): I had a rough
idea of how they worked, based on my user's ecxperience; then
I grep -rI'd thru the code looking for access_allowed(), and I
ran a couple of troubled cases thru gdb (for proxyAuthz control)
to see who was actually calling that function.

I regret to admit that if I had the time to keep docs and releases
up to date and aligned, I would rather spend it for my employer's
projects, to reduce the number of complains I get from that side.
I'm afraid this is intrinsic in Open Source, and won't be eliminated
easily.

p.

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