Re: Answering frequently asked questions

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

> 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.

man pages are man pages, not a book
on "Zen and the art of crafting ACLs"

>
>> 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.

Nobody can prevent you from doing that.
But there's no guarantee that anybody
will read what you write.

>
> 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).

When I write "(unexperienced?)" I'm not
referring necessarily to you, I cannot
judge your level of expertise.  I'm
just stressing that my words best suit
unexperienced users.  And, there's nothing
wrong being unexperienced, since experience
is the only thing one cannot be born with,
but can be gained by acting appropriately ;)

> 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.

Then, why don't you put this together
and write a FAQ?  This is where FAQs
win against email archives.  For this
subject, one that is not able to get
it straight from te manuals could find
everything the right way in a FAQ
instead of in a partially misleading
thread of emails.  Interactive FAQs
allow corrections, while email threads
only allow add-ons.

>
> 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.

WHAT????? would you be fine having a document
coming with release X.Y.Z and documenting features
that disappeared in release A.B.C but nobody cared
to remove from the docs?  Would you like to be
submerged of emails like "why this doesn't work
any more, while the docs say it should?"

>
>> - 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 ?)

it does.

> documentation  should suddenly have some money value ?

I'm paid by my employer to spend some work time
on OpenLDAP, and I'm spending some of my spare
time on it as well.  Of course I tend to work on
stuff I like, and mostly on stuff that's needed
by my employer first.  If it works, my employer
is fine, they don't need docs.  If I have extra
time, I spend it documenting features I implemented,
and something more.  That's where (of course, with
contributions from otehr volunteers) slapd.access(5),
slapd-meta(5), slapd-monitor(5), portions of other
man pages, a few FAQs come from.

> 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 !

I'm saying that code is MANDATORY (we wouldn't
be talking about this, if there were no code,
just a bunch of useless docs), but docs are
not, for those who don't need them, stop.
That's why docs lag behind.  It's not nice,
but that's how it works, stop.

People who write docs, in IT industry, are
as valuable as programmers are, because good
docs (I mean docs that are worth reading, from
a technical standpoint) must be written by
a programmer or someone who's able to understand
how programs work.  In general, if you need
anything that OpenLDAP (or any other open source
project) does, you should really pay a lot
of money.  The fact that you get the code for
free doesn't imply you can also get consulting
for free.

>
> 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 ?

There is, and it is written in slapd.access(5)
as long as it is aligned with teh code, otherwise
it is written in the code.

>
>>
>> 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>

Is there anything wrong with it?  Someone
(I don't know Julius personally) started it,
the someone else added contributions.
Remember that the FAQ is what you put inside.
If you dont put anything inside, there's
nothing inside.  Of course, as far as you
don't contribute you'll never get compromised
with wrong or incomplete answers, and you'll
retain the moral authority to complain about
the FAQ being wrong or incomplete.

>
> 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).

Well, "forming a small group of people"
"software tool" "guidance from expert
developers" are sentences I hear everyday
in {end|use}less working meetings that
are good for those that do not have to
do the work, but are a hack for those
who should do the work but can't because
they're stuck at the meetings.  As soon
as you talk I'm not with you.  If you
start working I might be with you.

p.

PS: from my standpoint, this thread is
dead until I see something to work on.
Please, don't take it personally: I don't
know you, so how could it be personal?

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