[Date Prev][Date Next] [Chronological] [Thread] [Top]

Re: documentation [was Re: logging]

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/