<quote who="Craig">
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:
Excellent.
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.
Hmmm, which one? Every overlay is in the TOC.
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.)
The search works very well, I've never understood why it seems to be a problem?
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.
There are unix tools for this; apropos:
[ghenry@suretec]$ apropos rewrite CREATE RULE [create_rule] (7) - define a new rewrite rule DROP RULE [drop_rule] (7) - remove a rewrite rule TIFFRewriteDirectory [TIFFWriteDirectory] (3tiff) - write the current directory in an open TIFF file creat (3p) - create a new file or rewrite an existing one git-filter-branch (1) - Rewrite branches sepol_genbools (3) - Rewrite a binary policy with different boolean settings slapo-rwm (5) - rewrite/remap overlay to slapd
See the last one above.
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.)
2 hrs?
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:
Yes please. File it anywhere, we'll assign it.
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*. :> )
It's work fine for the OpenLDAP project. There are plans, just not very hig priority ;-)