[Date Prev][Date Next]
[Chronological]
[Thread]
[Top]
documentation [was Re: logging]
Howard Chu wrote:
> When you're looking for a software feature, the manpages and Admin Guide
> should be your first resort. Pretty much every feature is documented.
This morning there were some posts about "rewriting overlays". So, I
wanted to learn more about what they could do. I resisted the urge to
use Google and went directly to the OpenLDAP Admin doc:
http://www.openldap.org/doc/admin24/
First, let me say that the docs do look really complete. But, this is
good and bad. The bad part is that it is a little overwhelming. Can a
search be added to the admin docs? I wanted to know more about a
specific overlay and didn't see it in the table of contents. So, I
didn't know where to start... Google is the next viable option, IMO.
The FAQ-o-matic is very nice, but I think an updated interface would
help a great deal. (Not sure if the "faq-o-matic" package allows for
easy changes to the interface. And I am NOT suggesting removing a
perfectly good piece of software for something that looks nicer, but is
less functional.)
Lastly, the man pages... Again, the size is a bit daunting. There are 78
man pages with 2.3.35. (With an additional 121 symlinked files.) That's
quite a bit when you're looking for one specific thing and don't really
know where to start. I want to be very clear; I am NOT knocking the docs
at all. As I started looking around more, it is a lot more clear how
things are laid out. But, when LDAP is just a tool and not a core part
of my job, it is difficult to spend 2 hours reading docs for a feature
we may not even need. I was just looking for a quick description. My
hope is that my experience gives you more insight to what, at least, one
sysadmin finds difficult. (If I am the minority, then prioritize my
thoughts appropriately.)
> When a feature in the documentation isn't clear enough to you, it's fine
> to ask on the mailing list, but even better is to submit an ITS pointing
> out exactly what isn't clear. Sometimes we see problems on the list that
So (just to be clear), you'd want me to file a bug for adding a search
box to the admin docs? I looked at the bug pages and didn't see anything
about searching the docs:
http://www.openldap.org/its/index.cgi/Documentation
On a side note, I noticed that jitterbug is no longer being maintained.
Have you considered migrating to, say, Bugzilla? (I do realize how big
of an undertaking that is, I am *just asking*. :> )
Thanx
Craig