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

Re: documentation (Was: ACL Problem, Insufficient access (50))

Sorry to clutter the list by continuing this oft-repeated thread, but on the eve of what was at least once a charitable holiday in my own cultural tradition I feel the need to add 2c from my collection.

Tony Earnshaw wrote:
Alain Williams wrote:
On Fri, Dec 23, 2005 at 07:49:44AM -0800, Kurt D. Zeilenga wrote:
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,
see <<http://www.openldap.org/faq/index.cgi?file=730>http://www.openldap.org/faq/index.cgi?file=730>.

I am aware of that, however as I noted, the documentation really needs to be done by
those who truely understand openldap. I know that having to write documentation is
boring and a pain, but without it the s/ware will not be used properly.

Correction: will not *always* be used properly. There are by all accounts hundreds to thousands of people using OpenLDAP without issue. One Tonni Earnshaw made this point quite effectively to me several years ago.

Tongue-in-cheek: Maybe someone who really understands OpenLDAP could attempt to emulate MySQL's doco, beginning at OL 2.0 and carry it through to OL 3.2, with all possible pros and cons.

The MySQL community and its market are an order of magnitude or two larger than OpenLDAP's. For example, a search on amazon.com lists 239 books on "MySQL", while "OpenLDAP" yields exactly 3. That includes the seminal "Understanding and Deploying LDAP Directory Services" by Tim Howes et. al. which mentions the OpenLDAP project on all of 2 pages (dealing with the C API). The results also include the slender O'Reilly volume "LDAP System Administration", which you'll note doesn't have OpenLDAP in its title and was written by a Gerald Carter, who AFAIK was never an OpenLDAP developer, from whom I have never seen a post on this list, and who IMHO could have written a far more useful text than he did.

As a well-known Java developer once reported, documentation is a death by a thousand cuts. There is no doubt it's necessary, but it is an understatement to say it's not easy to produce something that will pave the way for all users. This is exponentially harder in a project that innovates at the rate of OpenLDAP, or that is flexible enough to continue accommodating scores of outmoded approaches (gdbm, slurpd, ...etc.).

The core developers, busy as they clearly are, can in some ways also be the most handicapped in doco production. Professional educators use the term "expert blindspot" to describe the problem of explaining something complex and thoroughly understood to somebody who knows nothing to start. In my experience, the ability to solve challenging problems and the ability to clearly explain solutions to the uninitiated are two distinct forms of genius. Put another way, there is a reason we don't just read Newton's or Liebniz' original writings in high school calculus classes.

I happen to think the Admin Guide is pretty damn good. The man pages are closer to current, and are fairly thorough. The FAQ-o-Matic and mailing lists, while not cohesive or real easy to navigate, are a meaningful stab at filling in gaps. Empirically, a large portion of the questions that come to this list are answered in these places.

A sweeping criticism like "the documentation is bad" does nothing to solve the problem. That doesn't mean you need to go write your own, but I imagine it would help a whole lot more if you pointed out where the documentation is particularly lacking so that the shortcomings can come to the attention of developers and perhaps be addressed. The ITS system is available to everyone and it states explicitly that it can be used for documentation issues as well as code bugs. In contrast to popular wisdom, I've seen the core developers respond to documentation needs when they become aware of them on several occasions.

So peace on earth, good will towards men, and perhaps we'll find a more cooperative community in our stocking ;)

Jon Roberts