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


Quoting Howard Chu <hyc@symas.com>:

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

Yes, and the only way to contribute to it is understanding the issue
(perfectly) yourself. If the documentation is wrong, then how am I to
know that it IS wrong, my UNDERSTANDING of it is wrong, or... ?

So the next time, don't say "it's in the FAQ/documentation" (or whatever).
Include a link to WHERE it is documented (and VERIFY that this link is
still valid)...

I can't contribute if I'm not taught how it REALLY works...

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

No, but one of your 'responsibilities' (not cut in stone though) is help
'your users' to understand the issue at hand. If 'you' tell them to go
read the manual/documentation/faq, then it should be CORRECT..

If it shown that it's wrong, at least have the decency to apologise
and fix it 'right away'. Keeping a faulty/lacking documentation and
keep refering to it isn't helping anyone.

> That is not how a community is supposed to work.

I think I've contributed quite a lot of documentation to be allowed to
question the quality of the OpenLDAP documentation...

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

What I mean by that is that I've actually seen references to '4KB', but
using the value '4096' was WRONG! I haven't seen this in the OpenLDAP
documentation though (I think it was 'raidtools' or something like that).

So, in that case my assumption was wrong, and the docu was right. But
I still think there is things to wish for in that specific page... It's
not clear _enough_.

> Since the subject matter is technical, writing about it in informal
> language will only cloud details.

Figuring out what value to use is not 'technical' per see. It's a 'simple'
mathematical formula. In any mathematical formula there is a 'simple'
(human) description on what it is (with references). That is perfectly ok
to de-techicalize (hmmm :).