tomcat-users mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Konstantin Kolinko <>
Subject Re: Tomcat 7 documentation weaknesses
Date Thu, 26 Jan 2012 09:36:05 GMT
2012/1/26 André Warnier <>:
> 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.

There is on pages.
There are tips in several places on how to use the search box.

It is supposed that your Tomcat documentation is in http://localhost:8080/docs/
The one on  the web site is just a copy.  Well, external search engine
is of little help on localhost. But you are right that Lucene might

> 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 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 "", 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).

If you type "tomcat 7 jmx" you will get results that you want.

See also SEO issue in Bugzilla

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

1. It is better to read the whole docs at once, or at least look through them.

2. The pages are listed here:

3. There is "5) Manager"

Well, I would say that I do not like some things in the docs, and I
think that the structure goes up to Tomcat 4 (as well as many FAQs on
the wiki), but fixing them takes so much time that it is frustrating.

Thank you for raising the issue, though.

If someone want to submit a patch, Bugzilla is the place. (And wiki is
editable by anyone).

> 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
> (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 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
> 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
>, 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 ?

Best regards,
Konstantin Kolinko

To unsubscribe, e-mail:
For additional commands, e-mail:

View raw message