[Date Prev][Date Next] [Chronological] [Thread] [Top]


Turbo Fredriksson wrote:

I've been going back and forth betwen '4' and '4096' so many times,
I've started to mix up my own code...

Sorry about this.

Quoting Howard Chu <hyc@symas.com>:

You misread. And yes, I wrote the text of that FAQ article. Since I
also wrote the code in back-bdb that is being described, you can be
sure the description was accurate at the time of writing.


----- s n i p -----
For all of the people out there writing their own personal pages with
tips/notes/whatever - PLEASE consider submitting them as documents for
the OpenLDAP site to publish first/instead. Then there is at least
some possibility that the content can be checked for correctness, and
also some possibility that the content will be maintained and kept up
to date.
----- s n i p -----

I especially like the last part of the last sentence...

I continue to think that the OpenLDAP documentation sucks...

As we say over and over again - the FAQ is interactive, anybody can contribute material to it. The OpenLDAP project is a community effort. If you think that this area is weak, then you should contribute fixes for the Project to incorporate. It is not merely the developers' responsibility to make all of this Project work. You should not assume that I or anyone else among the developers is always keeping tabs on every little sentence on the OpenLDAP.org web site. As users, this is one area in particular where all of you can give something back to the Project. As developers, we've got a lot of things to deal with already. The FAQ grows on an ad hoc basis; that is the nature of an FAQ. The fact that you've pointed out this particular article is out of date should be a prompt to someone to update it, yes. But to expect that "someone" to be one of the developers is expecting too much, expecting others to do all the work so that you can simply enjoy the benefits. That is not how a community is supposed to work.

As long as the documentation is CORRECT, I have no problem with it. You
think it's 'perfectly clear' because you know the inner workings of
the software's you're coding for.. I couldn't care less! I'm a user/admin,
I have no need/will to know how it works behind the scene with structures
back and forth, if they're int's, float's or what not.

No argument there.

I need a working calculation example. Using '4KB' as number and/or not
explaining (CLEARLY!) where the number come from (with command line
examples etc) will just look like magic, and will only complicate things
for 'everyone'.

Perhaps you would have preferred "KiB" according to the new standard. These abbreviations have been in use in computer jargon for over 30 years, so calling "4KB" unclear does not reflect well on your commentary.

All mails asking the same question over and over again PROVES this! EVERYONE
seem to have problems in getting KerberosV+CyrusSASL+OpenLDAP working,
so the 'rubbish' (sorry, I think it is) that the OpenLDAP documentation
is sufficient/good/whatever don't hold truth...

No. It proves that people are leaping into that problem without looking first; trying to use X+Y+Z without first understanding X, Y, and Z on their own. It is unrealistic to expect to succeed at such an effort. It is also unrealistic to expect this Project to provide detailed tutorial documentation on X+Y+Z when the only thing we have control over is 'Z'.

NO ONE have 'complained' about _MY_ documentation/book (more
than the obvious spellingerrors etc :). It have helped EVERYONE
trying to get it working. It is written in _HUMAN_ english, not
_TECHNICAL_ english.

Someone said that 'never let a technician write documentation'..
I couldn't agree more!

Since the subject matter is technical, writing about it in informal language will only cloud details. The imprecision in "human" English is detrimental in technical documentation. (For example, the normal English rules of punctuation require the punctuation to be contained within any quotation marks, such as "this," and "that." But when writing documentation and attempting to illustrate precise syntax and keywords, this rule just serves to obfuscate the examples, e.g.: ' the correct DN is "cn=foo." ' )

A well-written document is no different from a well-written program. It has structure, form, a flow of logic, and rules of syntax. Spelling errors interfere with interpretation of both, but unclear logic renders it incomprehensible. Obviously the subject must be crystal clear in your own mind before you can write about it with clarity. Just because someone is technically minded does not make them a poor writer. What makes anyone a poor writer is simply lacking the clarity of thought, and that lack of clarity is self-evident whether they're writing code or writing prose.

Btw, http://sapiens.wustl.edu/~sysmain/info/openldap/openldap_configure_bdb.html
isn't much better. I agree with you (in the msg00129 above) that

And anyone who blindly follows such unqualified advice is an idiot.

My intention is to rectify this, but I must understand the subject myself, before I can give ANY advice etc and I hope you can (continue) to help out here... My fault above (kbytes versus bytes), but I would like to defend myself (very vaguely :) that all those numbers just made my head spin :)

Probably, when your head is spinning, it's time to get up from the computer keyboard and go do something else for a while...

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