Re: documentation [was Re: logging]

[Howard Chu <hyc@symas.com>]

Craig wrote:
> 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.)

Aside from Gavin's reply re: apropos, there's also grep and other tools. I 
don't see that any of this is an obstacle to a Unix sysadmin. If it's a 
challenge to you, I suggest you immediately go buy a copy of 
_The_Unix_Programming_Environment_ and read it.

When people complain that thus-and-such feature hasn't been documented, that's 
a legitimate flaw. I have no sympathy for people who complain that we have too 
much documentation. (Heck, I think that's even the first time anyone has ever 
made that complaint. Usually they're comparing us to the mountains of verbiage 
folks like Sun and Netscape/RedHat ship and whining about how that must mean 
our docs are incomplete.)

Again, learn how to find information efficiently. It's not that hard, but it's 
a prereq to being able to do your job at all.

> On a side note, I noticed that jitterbug is no longer being maintained.

"Maintained" is an interesting word, in open source. The source code is 
available, and it's completely under our control. We've tailored it to do what 
we want it to do. As such, I don't think you can call it unmaintained.

> Have you considered migrating to, say, Bugzilla? (I do realize how big
> of an undertaking that is, I am *just asking*. :> )

Yes, we've considered it. Like just about everyone else, there are far more 
things that need doing than we have time to do.
--
  -- Howard Chu
  Chief Architect, Symas Corp.  http://www.symas.com
  Director, Highland Sun        http://highlandsun.com/hyc/
  Chief Architect, OpenLDAP     http://www.openldap.org/project/