Re: documentation [was Re: logging]

["Gavin Henry" <ghenry@suretecsystems.com>]

<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:
>
> http://www.openldap.org/doc/admin24/

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:
>
> http://www.openldap.org/its/index.cgi/Documentation

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