Re: documentation [was Re: logging]

[Craig <craig5@pobox.com>]

I was very hesitant to respond because flame wars are simply a waste of
time and serve no purpose. However, I find it simply too condescending
to let it go. Also, you posted your reply publicly, so I will as well.

Howard Chu wrote:
> 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

I explained in my reply to Gavin why that didn't work. Don't assume that
every environment is set up the same way yours is... (We all have
something in our environment we would like to fix, but don't have the
time.) Also, don't assume that fixing man pages for one application that
is working fine is anywhere near the top of my priority list. (I will
accept criticism for not having the man pages in a spot where they are
indexed or for forgetting that they are not in said spot. But, I will
not accept statements that say I do or do not know how to do something
when you clearly have no idea.)

A simple response of "man -k rwm" would have been perfect. (Which is
exactly what Gavin did.) I would have then realized/remembered that my
(or the "system") man path needs to be updated and that makewhatis needs
to be run.

> a challenge to you, I suggest you immediately go buy a copy of
> _The_Unix_Programming_Environment_ and read it.

If you are going to suggest a book, I would recommend choose something
more relevant, or least something that has been updated in the past 20
years. That book is seriously out of date. Also, I believe there are
several other books that are significantly better:

http://www.amazon.com/UNIX-System-Administration-Handbook-3rd/dp/0130206016/ref=pd_bbs_2?ie=UTF8&s=books&qid=1197344200&sr=8-2
http://www.oreilly.com/catalog/esa3/
http://www.oreilly.com/catalog/upt3/


> 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

I would strongly suggest you actually READ my email next time.

"I want to be very clear; I am NOT knocking the docs at all."

I really do NOT (do I have to say it again?!?!?! ***NOT***) see why this
was so difficult to understand.

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

Do not assume that you understand the first part of my job or what it
entails. You know almost nothing about me, yet you know what the
prerequisites are for my job, or even what exactly my job really is?!?!
How many scientists do sysadmin work because they can't get a grant to
cover hiring one?

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

I find this probably the most ironic of your entire message. You are
critisizing me for, in essence, being lazy and not reading the docs or
knowing how to find information. If you go to the OpenLDAP ITS main page;

http://www.openldap.org/its/

There is a link for Jitterbug at the bottom. (I only point this out,
because I don't know if this link is the "correct one". It is simply the
one list on your web pages.)

http://www.samba.org/jitterbug/

At the top of that page, there is the following statement:

	JitterBug project suspended

	The JitterBug project is no longer being actively maintained.

Realizing that people are busy, I was *merely* pointing this fact out.
Nothing more.


I want to may sure this is clear; my original message was simply saying
what *I* found difficult. I even said:
	 "If I am the minority, then prioritize my thoughts
	appropriately."

In the end, I was asking a pretty simple question and letting you know
what I found difficult. I was very clear that I was NOT (again, let me
say it twice so maybe you will actually *SEE* it... ***NOT***)
criticizing the docs or the web pages. I was just trying to suggest a
possible improvement.

In the future, I will be much more careful about giving any kind of
feedback to the OpenLDAP community.

Craig