Hi.
Please see this this as a "constructive critic", not as a complaint.
The on-line documentation of Tomcat is not always easy-to-use, particularly when one is a
relatively naive (or new) Tomcat user, and does not necessarily know what precise term to
look for, or what belongs where.
First, there is the lack of a "search" box on the Tomcat pages.
I am a bit surprised that there exists under the Apache umbrella a powerful java-based
search engine (Lucene) with a servlet-engine based user interface (Solr), but that it does
not seem to be used anywhere else than on the Lucene pages themselves (and certainly not
in Tomcat pages). And this although I am ready to bet that an overwhelming number of
Lucene installations use Tomcat (with Solr) as their user interface.
The main site www.apache.org does have a search box, but it uses Google (Eeek, a
commercial outfit !), and its results are not always what one would expect, Tomcat-wise.
For example, if I enter "tomcat jmx" in that search box, it does list a number of relevant
pages from the site "tomcat.apache.org", but none of these pages is for Tomcat 7 (they all
refer to Tomcat 6 or 5.5).
(The same for "tomcat monitoring", and even worse for "tomcat manager" - which lists
mostly Tomcat 4 pages).
Another example : imagine that a new user would be looking for instructions as to how to
configure the Tomcat Manager application, starting from the Tomcat 7 top documentation
page at http://tomcat.apache.org/tomcat-7.0-doc/index.html.
Scanning the menu at the left (there is no "Tomcat Manager" item), his first stop would
probably be the item "21) Monitoring and Management". However, that leads to a page
talking about JMX, but not at all about the Manager application, which is not even mentioned.
And then what ? None of the other menu items seems relevant.
In fact, in order to find a mention of the Tomcat Manager app, one has to use the menu
link "4) Deployer", which is a tad counter-intuitive.
In that page, there is a link "Deploying using the Tomcat Manager" which helpfully leads
one to another link to "its own manual page", which links to the "Manager App HOW-TO" page
at http://tomcat.apache.org/tomcat-7.0-doc/manager-howto.html.
(So far, this is the only link that I have found which leads to that page).
Another example : imagine that a new user was trying to find out how to connect a
front-end Apache httpd server with a back-end Tomcat.
Starting from the Tomcat 7 top page, one might think about the item "20) Connectors", /if/
one would know in advance that this is one of the needed components. Unfortunately, the
page to which this links ("Connectors How To" at
http://tomcat.apache.org/tomcat-7.0-doc/connectors.html) does not say very much about
"front-end" or "proxy", and it links to nowhere else.
Another possible link on the main page would be "15) proxy support", which links to a page
"Proxy Support HOW-TO" at http://tomcat.apache.org/tomcat-7.0-doc/proxy-howto.html.
That page however talks mostly about Apache 1.3 and mod_proxy (HTTP); it does mention
mod_jk in passing, but mod_proxy_ajp not at all. And it does not provide any link to
follow for more precise information, not even to the main version-agnostic Tomcat
documentation page at http://tomcat.apache.org/, which does contain a "Tomcat Connectors"
link.
In fact, the "best" menu item to use seems to be "19) Load Balancer", which is also
counter-intuitive but which leads to a page which at least mentions mod_proxy and mod_jk.
The "Documentation - Tomcat Connectors" link on the main Tomcat page, does link to a much
more detailed documentation, but only only about mod_jk and the AJP Connector. Nothing
more about mod_proxy_http or mod_proxy_ajp there.
In the above, I may have missed some better links, but at least I think that they are not
evident.
To get back to the starting point of this would-be constructive critic, I believe that
finding what one is looking for in the on-line Tomcat documentation is often not easy for
people who use Tomcat occasionally, or for beginners. Maybe this explains why a lot of
people come to this list with questions which are already answered somewhere in the
on-line documentation, but on pages which they were not able to find.
And I believe that a search box on the Tomcat 7 pages, searching specifically the Tomcat 7
documentation pages, would go a long way to improve the user's experience with this site
and avoid repetitive questions on the user's list (and repetitive RTFM answers).
Does anyone feel like talking to the Apache Lucene people about some possible
collaboration with the Apache Tomcat site ?
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscr...@tomcat.apache.org
For additional commands, e-mail: users-h...@tomcat.apache.org
