I hate docs that tell you what to do, but not why. As soon as a package name or path changes, you're dust. This is maybe the 4th time I've been configuring Apache to delegate stuff to Tomcat using mod_jk, and every time is just like the first.
This time, my hiccups (so far) are:
mod_jk docs instructions:
1. "Install the package tomcat5-webapps" (I'm using Tomcat6 - easy to adjust for now, but...)
2. "Copy the example config file workers.properties to /etc/tomcat5/base" (there is no directory /etc/tomcat6/base - do I need to create it? Can't I just add a workersConfig option to the ajp13 listener?)
3. "Make sure CATALINA_BASE is set to "/srv/www/tomcat5/base"." Ummm... why? What does that have to do with mod_jk?
Some things I'd like to see:
* A short description of how ajp13/mod_jk works
* A short description of options I might need/want to change (say, if installing Tomcat as an unprivileged user, or on a non-standard port number)
* A short description of the various jargon around the task (what the hell is CATALINA_BASE? I know - which is why I know I don't need to change it)
* Any time I'm asking the user to do something, tell him how to do it (asks me to make sure CATALINA_BASE is set to X, but doesn't say where I might find the current value, or change it).
I guess I get to write a follow-up comment describing what I learned :)