tomcat-users mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From André Warnier ...@ice-sa.com>
Subject Tomcat 7 documentation weaknesses
Date Thu, 26 Jan 2012 00:18:24 GMT
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-unsubscribe@tomcat.apache.org
For additional commands, e-mail: users-help@tomcat.apache.org


Mime
View raw message