Re: Answering frequently asked questions

[Ace Suares <ace@suares.nl>]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1


Pierangelo,

Thanks for your answer, altough I feel ambiguous about it.

I'll take some portions of your mail and react to it.
>
> That's why Howard insists in telling you to read the code.
> In a perfect world, each release, even minor, would be based
> on carefully examining well thought documents of the first
> type, and come along with fully up-to-date documentation
> of the second type.

My issues are not with missing documentation for minor or major releases!

My issues are that, if we stay on the subject of ACL's, slapd.access(5) just 
doesn't cut it. It is verry brief, to say the least. Examples are sketchy and 
not 'complete'. With incomplete I mean often only one of the possible 
options/modifiers/styles is explained.

> I don't object, in principle, about reviewing documents
> written from an (unexperienced?) user's perspective,

Thank you. This is encouraging. This was the kind of commitment I hoped that 
would come from the developers. 

The 'private' mail Mr. Chu was sending me simply said: 'don't bother, you 
don't know enough'. That was not encouraging personally and, even worse, a 
reaction to the list (to the people that use OpenLDAP) was omitted. The 
reason that I don't let go is that I *want* to understand OpenLDAP and 
especially ACL's.


> different from my usual practice.  However, in my
> (learing and teaching) experience, it is quite useless
> to write about things one doesn't know enough, and
> significantly about things that require a broad view
> of the subject, although missing some of the details.

Two points here - first, if one doesn't know enough about something and there 
is no other source of information about it, what's the best road to knowing 
more about it? Start researching it and writing about it ! I thought that was 
how all science, even computer science, was supposed to work.

Second, I severely MISS the broad view of the subject. Where can I find such a 
braod view ? Maybe if I found some document with that broad view, I wouldn't 
have so many questions (and maybe you'd stop mistaking me for an 
unexperienced user).

>
> In this case, an HOW-TO tends to become what I call
> an HOW-I-DID-IT, or even an HOW-I-THINK-I-DID-IT, which
> in most cases is useless because it is too much dependent
> on hardware or software details and versions, and
> sometimes amy even be misleading.

Just have a look at the recent discussion on this list about 'webregister'.
1. A question is asked
2. A 'how i think i did it' answer is given by an (unexperienced ?) user
3. A developer answers a slightly different question with a slightly different 
method
4. A 'how i think i did it was almost correct, but here is how to do it' 
answer is given by the (unexperienced ?) user
5. A 'well that's ridiculous' answer is given by a developer, because of the 
wrong interpretation of the original question
6. The unexperienced (sic) user is asking to explain what he did wrong
7. the developer agrees that the unexperienced user was not wrong and (wow!) 
actually explains something about 'entry'
8. the original poster goes with some version of (3)
9. (I was flabbergasted) the developer debunks (8) and corrects the answer 
with something similar to... (4) !

Now tell me, what more confusion can happen. When one searches through the 
mailinglist, and hits that thread, well, to say the least, one would probably 
still be confused.

However, even an unexperienced user could compile the original question, and 
the final answer (if we have a final answer) into the interactive faq, or 
some better on-line resource.

Questions like 'how do I let users write entries under their own entry, but 
not delete them' ? are very plain questions that need some plain answer. 
That's the kind of documentaton I am looking for. I hope I make myself clear? 
Some feedback is appreciated.
 
>  What is required is
> someone who is able to:
>
> - understand how things should be done the right way

Who should I write to ? Or where can I find a document that explains how to do 
the things the right way ? Is there a right way ?

> - understand how thing must be actually done, say, to
>    workaround software flaws, while highlighting the
>    need for temporary or (preferably) permanent fixes

That would be good, yes.

> - do it timely, i.e. right before a release is ready

Less important to me.

> - do it at the same time in a good language (English;
>    I'd be more comfortable in Italian, but not in Dutch,
>    for instance; nothing personal, though ;) and in a
>    correct manner.

Here is a point - many of the users of OpenLDAP are not masters in English.

> - other issues I forgot to mention

Your documentation of your method to document lacks, Pierangelo ;-)

>
> If you read carefully the above, you'll notice that
> I'm talking about anything but an (unexperienced?)
> user; I'm talking about the kind of person IT users
> are struggling for, and pay hundreds bucks per hour.

Strangely, OpenLDAP is developed by volunteers ( or not ?) but documentation 
should suddenly have some money value ? Come on, if there is programmers 
working on OpenLDAp that people pay hundreds of bucks for, surely there are 
people who can do this documentation work on the same basis as those 
programmers !

Or are you saying that 'ACLs grow as we progress with OpenLDAP and we 
developers don't know the heck what we are doing, so we can't provide even a 
clue to documentation ?' That's NOT what you are saying, are you ? There *is* 
a known way that ACL's should behave, isn't there ?

>
> Finally, in my opinion there is a means for users to
> contribute directly to the project, besides writing their
> own documents and posting them on some web site (even
> OpenLDAP's site is hosting third party stuff, if worth):
> the interactive FAQ. 

Apart from not liking the way the FAQ works, the entry for access control 
starts with:

<quote>
Warning: This is an attempt at documenting the access control facilities in 
OpenLDAP 2.0. I wrote it precisely because I did not understand them. So I 
started reading the source and collecting comments from the mailing lists 
until I could get the general picture. But I am not sure I have understood 
the thing myself. So please, please, please, do fix anything I got wrong. 
</quote>

Then, the examples and solutions that are given are sometimes not exactly 
'right'. Thus, in the FaQ there is already some initiative going on just like 
the one I propose. Except that it's hard to 'alter' solutions and efficiently 
work on improvements, the overall picture is missing, it's not 'complete', it 
doesn't mention too much of versions differences and software flaws... and 
since it's missing an overall picture, it's not categorizing the knowledge in 
a comprehensible way.

I appreciate the efforts of the person that started it -  I myself didn't 
start it because I'd have to put in so many 'wrong' things that the 'right' 
things would be hard to find.

What I proposed was forming a small group of people, some software tool where 
it is relatively easy to add comments and alterations, some guidance from the 
developers, to come to a structured and more comprehensive document. 

I can not understand why my proposal gets so much antipathy from the 
developers (just like the previous time I proposed someting similar). I guess 
the timing isn't right or I am not the right person. (There might be other 
reasons ut I don't want to think about them).

> I hope I clarified my thoughts.

Sure, and thanks for that once again.

_Ace

website: http://www.suares.nl * http://www.qwikzite.nl
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.2.2-rc1-SuSE (GNU/Linux)

iD8DBQE/5L/sy7boE8xtIjURAuMwAJwJXhuMfkBCZjidlu5TJ1Ek+qy+AQCfQH8/
pYh1tWi0Soab61eqOtdDYhU=
=N9pL
-----END PGP SIGNATURE-----