2012/1/26 André Warnier <a...@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-unsubscr...@tomcat.apache.org For additional commands, e-mail: users-h...@tomcat.apache.org
