You are viewing a plain text version of this content. The canonical link for it is here.
Posted to users@tomcat.apache.org by André Warnier <aw...@ice-sa.com> on 2012/01/26 01:18:24 UTC
Tomcat 7 documentation weaknesses
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
Re: Tomcat 7 documentation weaknesses
Posted by Mark Thomas <ma...@apache.org>.
On 26/01/2012 00:18, André Warnier wrote:
> Please see this this as a "constructive critic", not as a complaint.
Ack.
> 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.
Agreed.
> The main site www.apache.org does have a search box, but it uses Google
> (Eeek, a commercial outfit !)
So what? While the ASF has a preference for eating its own dog food
where possible, it also has zero problems with using (and paying for
where appropriate) commercial services even where an alternative open
source service exists if the commercial service is a better fit for the
problem at hand.
>, and its results are not always what one
> would expect, Tomcat-wise.
See https://issues.apache.org/bugzilla/show_bug.cgi?id=52235
> In the above, I may have missed some better links, but at least I think
> that they are not evident.
Patches welcome although some restructuring looks to be necessary as the
list how-to links has become quite long now.
> Does anyone feel like talking to the Apache Lucene people about some
> possible collaboration with the Apache Tomcat site ?
I think there are simpler fixes that can be applied first although
fundamentally what is required is a complete restructuring. I liked what
pid did with the Tomcat 7 start-up page. I'd love to see the whole
website and docs look something like that.
Some other references while I am here:
https://issues.apache.org/bugzilla/show_bug.cgi?id=16579
https://issues.apache.org/bugzilla/show_bug.cgi?id=48672
https://issues.apache.org/bugzilla/show_bug.cgi?id=49122
Some requirements to keep in mind for the documentation pages:
- The source needs to be in svn
- The form that the edits are made in needs to be simple to work with
- We need to be able to generate the HTML as part of the build process
- The website and the docs should have the same look and feel (I'd be
happy if the old docs didn't)
Improving this comes down to someone having the time and the skills to
improve things. As always, volunteers welcome.
Mark
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@tomcat.apache.org
For additional commands, e-mail: users-help@tomcat.apache.org
Re: Tomcat 7 documentation weaknesses
Posted by Pid <pi...@pidster.com>.
On 26/01/2012 00:59, David Kerber wrote:
> On 1/25/2012 7:18 PM, André Warnier wrote:
>> 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.
>
> ...
>
> And I always thought it was just me who could never find what I was
> looking for in the docs...
>
> Thanks for posting this, Andre!
I agree, largely - it's long been an ambition of mine to improve things,
but I haven't been able to make much progress yet. Was a bit more
complicated than I thought it would be when I started experimenting.
p
--
[key:62590808]
Re: Tomcat 7 documentation weaknesses
Posted by David Kerber <dc...@verizon.net>.
On 1/25/2012 7:18 PM, André Warnier wrote:
> 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.
...
And I always thought it was just me who could never find what I was
looking for in the docs...
Thanks for posting this, Andre!
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@tomcat.apache.org
For additional commands, e-mail: users-help@tomcat.apache.org
Re: Tomcat 7 documentation weaknesses
Posted by Konstantin Kolinko <kn...@gmail.com>.
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