<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 ;-)
Gavin Henry wrote:
<quote who="Craig"> Hmmm, which one? Every overlay is in the TOC.
Yes. But, the overlay was referred to as "rwm". If you do a simple search on that (TOC) page, you get no results.
http://www.openldap.org/doc/admin24/
I want to reiterate that this only because I was curious. There weren't a ton of log messages that said it was causing the server to explode or anything. Since I didn't know exactly what it did, and didn't know where to start, so I turned to Google next . All I was trying to say is that a simple search of the admin doc would have gotten me exactly what I wanted.
Ok, based on another post, I want to be perfectly clear... This is NOT (do I have to say it again?? NOT) a criticism. The docs are great. But, if you don't know where to start, trying to glance at 20 chapters and 13 appendices is a but much for something you saw in a "random email".
The search works very well, I've never understood why it seems to be a problem?
I think it's because it's become kind of the defacto standard that to "search" you look for the little box, not a link that says "search". In a previous job, my group did some usability studies and found that people found the search significantly faster when there was a textbox as opposed to a link. Also, having it on the bottom of the page kind of hides it. (Again, NOT a criticism!!! The search *IS* there... it's just not in an obvious place... and, yes, "obvious" is very relative.)
There are unix tools for this; apropos:
I am familiar with "man -k". Unfortunately, I had some problems (with replication) months ago and was advised to install the most recent version. It was installed in a non-standard location. So, it's not in the man path and therefore not indexed. (Yes, I am well aware of how to fix it.. but, it's simply not a high priority. ;> )
2 hrs?
Ok.. you caught me. That was a bit of an exaggeration. (I was eating lunch... got interrupted with questions... etc.) But, you do understand my point, right? I was merely saying that by following your instructions (going to the admin docs BEFORE going to Google), I would have found what I was looking for in literally 20 seconds if a search box was there. That's all.... No slight against the docs, or anything else. As has been mentioned many times, we are all busy and I am JUST suggesting that a search box would have helped me in this particular instance. (And, yes, I full take responsibility for having a slightly screwed up environment where man -k doesn't have every man page indexed...)
Yes please. File it anywhere, we'll assign it.
I am filing it now... AFTER I read the "how to report bugs effectively" page. ;)
Craig wrote:
I want to reiterate that this only because I was curious. There weren't a ton of log messages that said it was causing the server to explode or anything.
I knew we were missing a log message somewhere. I suppose it ought to finish with "Click OK" as well...
openldap-software@openldap.org
-
Craig -
Gavin Henry -
Howard Chu