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