Understood. I felt the same way when I started with Tomcat. The documentation is under review, and will be updated. I know this and can say this because I am one of the people doing the reviewing (what little I have been able to get done so far due to time constraints). Again, though, it's the open source model, and the Apache method. That means that there are no timelines, no delivery date guarantees, and no promises. It is what it is at that point in time. Sometimes it sucks, sometimes it doesn't.
I think though, that making a generalization is unwise. Tomcat actually is very well documented, when you consider that it's the reference implementation of the spec. The spec gets quoted here quite a bit, and is available to anyone who wants to read it. If you want to know what something is, or why it is, or how it is, you can read the spec. The source code is always available, too. I've been subscribed here for six months now...a lot less than some, maybe more than most. The difficulties that people have, by and large, are 1) application oriented and 2) related to Apache integration with a connector. By #1 I mean that many people jump into writing servlets and JSP and find that it isn't that simple and that the application design and architecture was broken from the beginning, and choose to blame Tomcat for that (at least initially) until corrected. By #2 I mean that the Tomcat team has enough to do without having to worry about integrating with Apache. Integrating with Apache isn't required, it's an optional configuration that is used by a lot of people, granted, but it isn't required or necessary for Tomcat to be developed or used. The number of posts related to problems with Tomcat itself, like setting up SSL, or managing connections and processes, or memory management, or whatever, are proportionately quite small to the total. I think a big step towards alleviating a lot of the frustration would be to have an FAQ, and that's something I would like to pursue. that would give people more time to research more difficult problems and questions. I know an FAQ would probably save me a couple hours a day. I don't mean to sound like a jerk, and there were many times in the past when I felt exactly as you do when using various open source projects over the years, but the solution isn't ranting or complaining, but instead asking yourself "how can I help?" and "how much time can I devote to helping?" That's not me being arrogant because I am one of those who tries to help, it's me describing how the open source model works. I know everyone knows how the model works, I can only assume that frustration causes people to complain and criticize. That's fine, I've done it myself unfortunately, but it isn't the solution, and it certainly doesn't help. Believe me, I'm well aware of when I make an error or a HOWTO that I wrote isn't clear, I get emails from all over the world asking for free help when it happens. The only solution, for me or for anyone else, is to keep plugging away, and to keep hoping that the project itself stays interesting and challenging, because honestly, that's the only incentive. That, and the desire to give back for something you got for free in the first place. I think the main problem is lack of continuity. There are several places where it says "don't use webapp" including the connector itself. Heck, people post here and say things like "I read that I shouldn't use WARP, but its just so darn easy to use, can I use it?" What do you answer to that? Should they be ignored? JK is, in my opinion, the only production stable connector for 4.x, I think not having documentation for it would be more of a disservice than the opposite. But that's me. When you consider that the connector teams aren't the Tomcat team (generally speaking), it gets even more messy, especially on the Apache side or IIS side. I don't think it's reasonable to expect the Tomcat team to devote resources to making everything warm and fuzzy with IIS, for example. I don't think that will ever go away, awesome documentation or not. Tomcat is not a web server, and in many places it can't be used as one due to legacy constraints or other requirements. The connectors and the issues that come with them are here to stay, I think. John > -----Original Message----- > From: Jerry Ford [mailto:[EMAIL PROTECTED]] > Sent: Wednesday, December 18, 2002 5:09 PM > To: Tomcat Users List > Subject: [off-topic] Re: jsps and servlets don't work > > > /*********************************** > * > * Caution: LONG Rant Warning :) > * > **********************************/ > > > > Turner, John wrote: > > >I don't think they are poorly documented at all. Just the > HOWTOs written by > >myself and others on this list alone provide comprehensive > documentation. > > > > > John: > > // begin rant: > > With all due respect and recognition to the enormous efforts you > personally appear to have put into making Tomcat accessible, the > documentation is neither comprehensive nor adequate, for > either Tomcat > or whatever is the connector du jour. There are pockets of good > documentation, such as your how-tos and seemingly tireless > presence on > this mail list, surrounded by lots of chaffe---incomplete, > inaccurate, > out-of-date, even non-existent files inside of tarballs or littered > around the jakarta.apache.org website. > > I don't mean to rag on you, or the Apache group. > > I know it's all free software and, though it may not sound > like it, I am > an appreciative fan, now that I have stumbled onto this list > and located > your how-to page. > > But I've spent a lot of time fruitlessly searching the > jakarta.apache.org website for answers to my questions and I > have found > the doc set taken as a whole to be contradictory, poorly > organized, and > in some cases downright misleading. > > If you have any pull with the development team, IMHO, you > ought to ask > them give the website a thorough going over, removing old, > out of date > stuff (if mod_webapp and mod_jk are deprecated, why are they > included in > the connectors tarball with nothing in the READMEs to suggest > they are > out of date?) and updating whats left so that the entire doc set > accurately reflects the current state of the software. > > // end rant :) > > Jerry > -- To unsubscribe, e-mail: <mailto:[EMAIL PROTECTED]> For additional commands, e-mail: <mailto:[EMAIL PROTECTED]>
