Apache docs suck

I've said it before, and received a ton of crap for it....Apache's docs suck.

Consider this...you go to buy a new car. You find the one you want, and proceed to make the purchase. The salesman then explains that what you're going to do next is head to law school so that you can pass the bar. You see, the sales contract for a new car is very complex, and not something to be taken lightly. So, when you're done with law school in four years, come back and we'll do the deal. So, you do it. You pass the bar and you come back to buy your car. Of course, it's been four years, so you have to buy a different car. You manage, however, to get through the sale and are happy with your shiny new car.

A few months down the line your "Check Engine" light comes on. You read through the manual and it tells you that this could be anything! It's the ultimate dummy light, as it literally represents hundreds of possibilities of what could be wrong. You call the dealer, and ask for service. A heavy sigh comes from the other side of the phone as the mechanic gives the stage whisper, "Newbies". He explains that, yes, the "Check Engine" light could be indicitive of anything, and there's no way he can tell you what's wrong without some information first. So, he asks you to disassemble your car, and give him the serial and part numbers engraved on every component that makes it up. When you explain this is too much work, will he please just tell you how to fix it again comes the heavy sigh followed by, "If you wanted other people to fix all of your problems for you, why don't you just take the bus?!" So, it's off to school again for you as you begin your studies as a mechanic. After a couple of years, you feel confident enough to disassemble your car, but now you also know how to fix the problem, too! Yaay, no more dealing with that gruff mechanic! A feeling of accomplishment flows over you as you realize he wasn't just being gruff. He wanted you to get to that point of satisfaction of doing the job yourself. What a wonderful fellow he was!

Bullshit.

Apache docs pretty much tell you, "Apache is a webserver" followed by "here's all of the hundreds of possible commands you could put in your config file to make it work. We've specifically avoided telling you which ones are the barest essentials to get the system up and running if all you want is a small webserver to play around with something. Good luck."

Oh, yes, you're right, Apache DOES come with a default configuration file that does provide you with a minimalistic server that works. However, that file is 1086 lines long! Yes, there are comments above each set of commands that make the file that long, and if you remove them, the file is still over 300 lines long. My point? When I setup my first Apache server, after scouring the web for weeks for hints and such, my configuration file, for a basic setup, was 15 lines long. I had the barest of essentials: I could point a browser at it, and it would show web pages. Again, yes, there are HOWTOs. They suck, too. Don't say it, I'm already writing a good one.

But, what's even better is they're wrong in spots. For example, when compiling Apache from scratch, you use a configure script like most GNU software. Let's say you want to install all of the DSOs that come with the standard distribution, just so you have them. I hate having to recompile because I forgot to turn on some function of the software. To do this, the docs say use something like "./configure --enable-shared-dso=all". Makes sense, you want all the DSOs, you should prolly say "all". Problem is, "all" isn't "all". If you want, for example, proxy support, you have to tell it that specifically. Apparently "all" means, "all that we think you need, not all there is".

It gets better, using "--enable-shared-dso=all --enable-shared-dso=proxy" doesn't work, either. Here's the undocumented command: ./configure --enable-shared-dso="all proxy http_proxy etcDSO". Note the quotes which aren't noted in the docs. In all fairness, it's been a while since I graduated from Apache mechanic school, but it wasn't that long ago that this stuff wasn't well documented. I don't know if they've fixed it, and I don't care. Apache's been around for a long time, and I'm sure I'm not the first one who encountered this. In fact, when I asked, I was told, "here comes this old chestnut again!"

Here's a thought, boys: FIX YOUR DOCS!!!