Re: Answering frequently asked questions

[Ace Suares <ace@suares.nl>]

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

_Ace


>
>   -- Howard Chu
>   Chief Architect, Symas Corp.       Director, Highland Sun
>   http://www.symas.com               http://highlandsun.com/hyc
>   Symas: Premier OpenSource Development and Support

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

iD8DBQE/47H4y7boE8xtIjURAmh/AJ9JbKVCgHF46QWxn3JZksElIuFi7QCfXeQQ
8huPCuDs0BcUvbfLplazboA=
=viO/
-----END PGP SIGNATURE-----