On 2/11/07, Adam Tauno Williams awilliam@whitemice.org wrote:
Emmanuel's point is worth noting: it is very difficult to learn the OpenLDAP jargon, and the official documentation (the admin guide plus the FAQ, plus the man pages) quite simply don't cut it. They are steeped through and through with LDAP technical jargon (often used inconsistently, like "slave","shadow," "replica," and "subordinate" all referring to the server receiving replication by SLURPD or SyncRepl).
Sorry, but this is rubbish. Is the Samba documentation expected to explain how Windows works or serve as an introduction to SMB/CIFS networking? Half the terms above are generic LDAP terms; is someone wants to use LDAP then start with reading up on *LDAP*. Seems reasonable to become familiar with a technology before moving on to a specific implementation. If you think this applies only to OpenLDAP pop over to the Samba, Sendmail, Cyrus, etc... lists for people asking questions that are really about CIFS, SMTP, IMAP, etc...
Again, my main point was on the general tone of the list, not the quality of the documentation, though I see those two as strongly causally related. But I do see the point you are trying to make, Adam, so let me try to address your response.
I have the following problems with the argument presented above:
*. It is something of a straw-man argument. I am NOT arguing that one ought not need any knowledge to configure OpenLDAP. Nor am I arguing that BER or ASN.1 needs to be explained in detail in the admin guide (just as HTTP is not explained in Apache's docs, nor CIFS in Samba's).
But clarity in the documentation is certainly a desired feature, and as it stands now, it seems (based on responses to the list, as well as my own personal experience) that going from a small LDAP server following basically the default configuration to a more complex directory environment requires a pretty steep learning curve. Good documentation could improve that situation.
*. I don't find the argument that other products have bad documentation to be justification for not creating good documentation. To be honest, I think Cyrus' documentation is abysmal, and it took me years to get the hang of all of its quirks and inconsistencies. But I don't particularly care about that project. Samba documentation is awful, too -- and was the subject of a sustained rant from Eric Raymond some years ago. Sendmail does better... but perhaps not much better. At least it has the bat book.
I would even go so far as to suggest that much of the growth in postfix, exim, and the like is due to the poor documentation in sendmail and cyrus.
*. I don't actually think the problem with OpenLDAP is a *lack* of documentation (which is certainly a problem with Cyrus). Again, the man pages are very thorough and very complete. And if one reads the RFCs (which are also exceptionally good) and some of the code, then one can get along pretty well with OpenLDAP. But that seems to be a high barrier of entry. I'd like to see it get lower.
My opinion may be in the minority here, but I don't think that a prerequisite to running OpenLDAP ought to be the thorough and careful reading of the whole bundle of LDAP RFCs.
It isn't. There is *LOTS* and *LOTS* and *LOTS* of well cooked LDAP documentation - see Amazon. http://www.amazon.com/gp/reader/0672323168/ref=sib_dp_pt/105-2231389-9349228...
Tim Howes' book is excellent. I would certainly not dispute that. But at nearly 1000 pages, it's not exactly a breeze compared to the RFCs.
There is something to be said for trying to get people into LDAP from OpenLDAP. It comes with almost every major Linux distribution. Why not make it attractive to people who haven't yet discovered what LDAP can do?
Long ago, I read something Howard had written lamenting the fact that some of the more advanced LDAP applications he had conceived were beyond what people could comprehend a directory server doing. I feel the same way. The standard treatment of LDAP is as an authentication service provider. This is, of course, one area where LDAP excels. But it could be used for a lot more. Could lowering the barrier to entry with OpenLDAP contribute to resolving this misperception? I'd like to think so.
Asking the OpenLDAP project to re-document LDAP is unreasonable. Or SASL for that matter.
I'm not, per se, suggesting this.
As Howard pointed out, we know that the documentation could use improvement, and yet that doesn't seem to happen. Why? What I am suggesting, though I can see how it got lost in the fray, is that this list is on the tough side. And this generally negative attitude impedes improvement because it turns people away. And I am using Emmanuel's attempt to contribute to the documentation as a case in point.
Matt