Re: documentation [was Re: logging]

[Craig <craig5@pobox.com>]

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. ;)