On Friday 23 December 2005 13:17, Alain Williams wrote: > > 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. Note that many aspects of the "big picture" don't really relate at all to OpenLDAP ... and there isn't really any projects on documenting the big picture. Many existing documents are very outdated (to the point of being more effort to follow than they are worth). I have written some[1] in the past, but they are also out-of-date ... > > * 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) http://www.openldap.org/doc/admin23/schema.html > * 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. Lets not get ahead of ourselves yet. > * The manual pages seem to explain everything but in small pieces, complete > (non trivial) examples are lacking. Complete examples of what? Do they only cover the use of OpenLDAP, or other software as well (nss_ldap, pam_ldap, samba, sudo, apache, jabber, bind - to list just a few of the pieces of software I have configured to use LDAP in some way)? The "other software" bit is really off-topic for this list (and the official documentation). > * There is a lot of it: where do I start first ? http://www.openldap.org/doc/admin/quickstart.html ? That takes you about as far as it can without going off-topic. > 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. So, you're saying non-gurus should write (or at least contribute) to documentation? Are you volunteering? > 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/... These examples (mail/user_logon) would be very dependant on: -the MTA and/or IMAP/POP3/other mail protocol server being used -the application service the user_logon service (ie pam_ldap) The OpenLDAP developers shouldn't need to write other people's documentation. BTW, you may want to take up these issues on a better forum, such as the ldap-interop list. > This needs to be written by people who *really* understand openldap > otherwise what will be put together are examples of poor practice. I think it needs to be a combination, since some people need to give the guidance on what they found difficult to follow, and others would need to contribute documentation on that aspect. > > Notes: > > * RFCs are NOT end user documentation, they are reference for when you have > a good understanding of the topic. No-one said it was. If you have only been reading RFCs, you haven't been judging the existing documentation fairly. > * 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 think the OpenLDAP documentation supplied by the OpenLDAP project is sufficient for helping people deploy OpenLDAP. However, moving all authentication services to use your LDAP server has nothing to do with the OpenLDAP project (as any LDAP server could be used). > I know several good/competent people who have struggled with > openldap and given up frustrated, it is not through lack of trying. "openldap"? Or, deploying an LDAP service and integrating services to use it? > * Not everyone reads it with your eyes. There are means to contribute to the documentation. Regards, Buchan 1. http://linsec.ca/usermgmt/ldappdc.php -- Buchan Milne ISP Systems Specialist B.Eng,RHCE(803004789010797),LPIC-2(LPI000074592)
Attachment:
pgpJQIrnyfeCp.pgp
Description: PGP signature