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