[Date Prev][Date Next]
documentation (Was: ACL Problem, Insufficient access (50))
I note that the OpenLDAP Project is community developed.
If you find the documentation lacking, please feel free to
contribute documentation improvements. To get started,
At 03:17 AM 12/23/2005, Alain Williams wrote:
>On Thu, 22 Dec 2005 21:56:26 +0100, Pierangelo Masarati <email@example.com> wrote:
>> I don't know if that's part of the problem, but in your ACLs you're
>> building up most, if not all, the common errors that are widely
>> illustrated in slapd.access(5) and in the FAQ. Did you read (and
>> understand) any of those docs before implementing your own ACLs? I note
>> the OpenLDAP Project routinely gets complaints about the lack of
>> documentation; when documentation is available, it appears that people
>> don't really bother at reading (and understanding) it, so what really
>> pays back for the effort of writing and keeping it updated?
>> Ing. Pierangelo Masarati
>> Responsabile Open Solution
>> OpenLDAP Core Team
>Please take this as *constructive* criticism, it is not a flame.
>I also believe that the openldap documentation is poor. I have spent a lot of
>time trying to get simple things to work, I have cursed the poor documentation
>and the unintelligible diagnostics. I am someone who has spent > 30 years working
>with computers, the last 25 with many aspects of Unix, someone like me should be
>easily able to pick up openldap and work with it, but I can't, why not ?
>Summary: the documentation is too low level, the ''big picture'' and ''how to put
>it all together'' are missing.
>* I tried looking at the schemas, lots of numbers and names, no real indication
> as to how to use them (either in the .schema files or elsewhere)
>* I tried to look at the code: very few internal comments, whole functions without
> any at all, not even ''this function does X, takes A & B as parameters, returns C''.
> I would not let someone working for me write code like that.
>* The manual pages seem to explain everything but in small pieces, complete (non
> trivial) examples are lacking.
>* There is a lot of it: where do I start first ?
>The trouble with many openldap gurus is that you know it well, you cannot see it
>from the perspective of someone who is new to it.
>What is needed: more entry level examples that are complete, ie this is what the
>slapd.conf file looks like, here is a sample of data entries, here is how it is
>used for mail/user_logon/...
>This needs to be written by people who *really* understand openldap otherwise what
>will be put together are examples of poor practice.
>* RFCs are NOT end user documentation, they are reference for when you have a good
> understanding of the topic.
>* It is not fair to complain that people don't understand it, if the documentation
> is at a level that is much greater than their level of understanding. I know several
> good/competent people who have struggled with openldap and given up frustrated,
> it is not through lack of trying.
>* Not everyone reads it with your eyes.
>Parliament Hill Computers Ltd.
>Linux Consultant - Mail systems, Web sites, Networking, Programmer, IT Lecturer.
>+44 (0) 787 668 0256 http://www.phcomp.co.uk/