tomcat-users mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Konstantin Kolinko <knst.koli...@gmail.com>
Subject Re: Tomcat 7 documentation weaknesses
Date Thu, 26 Jan 2012 09:36:05 GMT
2012/1/26 André Warnier <aw@ice-sa.com>:
> 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 http://tomcat.apache.org/ 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
help.

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

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

See also SEO issue in Bugzilla
https://issues.apache.org/bugzilla/show_bug.cgi?id=52235

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

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

2. The pages are listed here:
http://tomcat.apache.org/tomcat-7.0-doc/index.html#Apache_Tomcat_User_Guide

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

Best regards,
Konstantin Kolinko

---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@tomcat.apache.org
For additional commands, e-mail: users-help@tomcat.apache.org


Mime
View raw message