Re: Answering frequently asked questions

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

Ace Suares wrote:
> -----BEGIN PGP SIGNED MESSAGE-----
> Hash: SHA1
>
>
> Hi,
>
> I am just posting my answer to the list, altough this message from Mr. Chu 
> didn't show up in the list (yet ?) but only in my personal mailbox.
>
>
> > Just my personal opinion - while I think you've shown a lot of energy going
> > down this path, the quality of your questions suggests to me that you're
> > not proficient enough in the topic (ACLs) yet to write a usable document.
>
>
> I agree with you - that's also the reason why I didn't start such document 
> yet.
>
>
> > It's not enough to have a volunteer who can put time into writing docs.
> > They have to understand what they're writing about.
>
>
> Indeed - I was hoping that apart from other people on the list combining their 
> understanding, developers would then actively participate in correcting the 
> solutions and explaining what they intended when they wrote code. From your 
> remark I am almost regretting bringing the topic up once again. But maybe I 
> am misinterpreting you - since you are always, errr... helpfull... on this 
> list.
>
>
> > Your complaint is that there isn't enough information, or it's not in
> > comprehensible language. When there isn't enough existing information, the
> > only way to find out what's going on is to read the code, because that is
> > all there is.
>
>
> I did go to university and learned a bit about axioms.
>
> I clearly have a the same axiom as you. But you draw a totally different 
> conclusion. My conclusion would be: When there isn't enough existing 
> information, one of the ways of finding out would be:
> - - first to pool all the information there is
> - - secondly translate the incomprehensible language to comprehensible language
> - - thirdly, ask the developers to give input (especially to questions like 'am 
> i right in assuming that a leads to b', and also in questions like 'when you 
> say a, can it be rephrased as b')
> - - and, fourthly, combine the efforts of many people, developers and 
> non-developers alike.
>
>
> > the
> > only way to find out what's going on is to read the code, because that is
> > all there is.
>
>
> If your code is not properly commented, it's bad code. That's my personal 
> opinion.
>
> If your code is properly commented, I don't mind reading code. However, I am 
> not bothering to try to understand 'memcopy(stralloc(&ber->val,STR_ACL_IN)))' 
> when you simply mean 'now tokenize the ACL before we parse each element'. 
>
> I hope, you get the point. If you can't take the comments and from there 
> rewrite the program in let's say Malbolge, you've written not a good program.
>
> I *did* read parts of the code.
>
> In short:
>
> # I can't understand it
> Geen touw aan vast te knopen ( zonder kennis van C++)
>
> You might be able to understand the dutch sentence, but if you're not, you'd 
> probably understand the comment.
>
>
> > If you can't read the code and understand it, then where are
> > you going to get the information to embed in your new document?
>
>
>
> I looked at the roadmap. There are many things there that might be might 
> interesting to maybe a very small group of people. At this point, I think 
> it's mighty interesting to produce some good documentation that is 
> interesting for a large group of people.
>
> If I am not the one to lead such a project - so be it. I hope someone else 
> will stand up then. I'd rather not spend time on something so obvious as good 
> documentation, to tell you the truth. I'd rather just read some 
> documentation, understand in full what ACL's (as an example) are all about, 
> and tweak configuration according to my needs. I have not been able to do 
> that altough since 4 years (since 1.0.27) I am trying to understand what's 
> going on. I assure you - that's not me being stupid, that's bad 
> documentation. Bad code, so to say.
>
> I press you to review your standpoint. 'If you can't read the code, then you 
> can't produce documentation' might be a good assertion - but the conclusion 
> could just as well be 'non C++ programmers can't write documentation' as well 
> as 'C++ programmers need to document their code (better)'.
>
> One last remark.
>
> I am not looking here for conflict or critique. 
>
> What I am looking for is cooperation to provide documentation for the 
> thousands that use OpenLDAP.

In the IT world there are roughly two types of documents:
pre- (call them RFC*, X*, draft-*, white paper) and
post- (call them man pages, admin guides, howtos or whatever).

The first type is always ahead of code (unless expired,
deprecated or so), the last type always lags behind.

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.

Since this doesn't even happen for commercial software,
despite the price you may get charged for, don't expect
it from open-source projects.

I don't object, in principle, about reviewing documents
written from an (unexperienced?) user's perspective,
and I do not pretend being an expert about every single
portion of OpenLDAP's code (actually, there are large
portions I never needed to look at), so I make my own
mistakes every now and then when I have to set up something
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.

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.  What is required is
someone who is able to:

- understand how things should be done the right way
- understand how thing must be actually done, say, to
  workaround software flaws, while highlighting the
  need for temporary or (preferably) permanent fixes
- do it timely, i.e. right before a release is ready
- 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.
- other issues I forgot to mention

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.

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.  I understand many people don't
like it.  Somethimes I contributed to it, other times
it takes longer than replying to an email, and surely
a collection of tiny pieces of solution don't necessarily
make up a good, comprehensive document.  However, this
is the way things should get together to be persistent.
Emails, even when archived, tend to be forgotten.
The FAQ is there, it can be periodically rearranged by
putting things together, merging similar issues and so on.

I hope I clarified my thoughts.

p.

--
Dr. Pierangelo Masarati         mailto:pierangelo.masarati@sys-net.it
LDAP Architect, SysNet s.n.c.   http://www.sys-net.it

+----------------------------------------------------------------------------+
|                                                                            |
|                     Buon Natale e felice Anno Nuovo                        |
|                                                                            |
|   SysNet - via Dossi,8 27100 Pavia Tel: +390382573859 Fax: +390382476497   |
+----------------------------------------------------------------------------+