[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
www.mentata.com