RE: [Tomcat Documentation Redactors To Hire] - WAS: TOMCAT SUCKS

[Bob Jamison <rj...@lincom-asg.com>]

At 08:56 AM 6/29/01 -0400, you wrote:
>It's funny how people can say, "TOMCAT SUCKS" but everyone and their sister
>is out there running it successfully.  If you take the time to read and
>understand the documentation that's out there, you can too!
>
>Anyways, speak of the devil, but I'm all about Tomcat documentation.  Unzip
>this into your $CATALINA_HOME/webapps/ROOT/docs dir (the one with all of the
>current docs in it) and let me know what you think.  It's more a
>look-and-feel template and an idea since I'm just getting back into "the
>loop," and haven't spent much time with TC4 (yet).
>
>Two things:
>
>1) I'd like to propose that we segment the documentation much more so than
>in 3.x.  Someone (Craig?, whomever) has done a really good, although
>incomplete =p job of this with the TC4 blue-framed docs so far.  This is
>much more manageable for doc authors, and MUCH less daunting for first-time
>Tomcat users.  I think people would be a lot more willing to read/proofread
>and maintain the documentation if the vertical scroll bar didn't get so
>small when they opened it =)
>
>2) Incorporate more of a FAQ into the user's guide.  If a newbie Tomcat user
>gets a BindException, they shouldn't have to look online to see what it
>means.  Same goes for "environment space," etc.
>
>Thoughts?
>
>- r
>
>p.s. Yes the HTML isn't what it could be, but that's not my area of
>expertise =)
>
> > -----Original Message-----
> > From: GOMEZ Henri [mailto:hgomez@slib.fr]
> > Sent: June 29, 2001 3:42 AM
> > To: tomcat-user@jakarta.apache.org
> > Cc: tomcat-dev@jakarta.apache.org
> > Subject: [Tomcat Documentation Redactors To Hire] - WAS: TOMCAT SUCKS
> >
> >
> > >     Not to get into a great big argument over OS version commercial
> > >products, but if OS projects expect to be taken with the same
> > >consideration
> > >as commercial they have to accept to be compared across the
> > board. This
> > >includes documentation. You can't just pick and choose the
> > >battles you want
> > >to fight.
> >
> > Could we close this thread positively ?
> >
> > We all know that tomcat documentation is incomplete and we need help
> > in that area.
> >
> > Tomcat IS AN OPENSOURCE project with a big user community,
> > Jon Stevens recently reported more than 50-100k downloads / month.
> >
> > Everybody could be involved in the project, and not necessary
> > developpers. I'm sure there is around potentials documentation
> > redactors.
> >
> > So who will be interested in working on the Tomcat Documentation ?
> >
> > ------------------------------------------------------------------
> >
> >
> > >For the most part, the documentation in OS projects
> > >just plain
> > >sucks, if it even exists. Believe it or not this is one of the
> > >reasons OS is
> > >often frowned upon. Look at Microsoft, sure its close source,
> > >people may
> > >think it sucks, blah blah blah, but do you have idea how much
> > >information is
> > >on MSDN?
> > >     The lack of documentation available goes against some very basic
> > >rules of Software Engineering. In the real world does this
> > >really matter? I
> > >dunno, but often times packaging and presentation, and a
> > >finished looka nd
> > >feel are the key to getting in the door and this is where most
> > >OS projects
> > >fail miserably.
> > >     Because its free might be the reason the documentation sucks, it
> > >shouldn't be a justification. (not that i'm saying tomcat sucks, just
> > >argueing the point).
> > >
> >
>


What a whiner  ;-)    j/k, honest, I perceive the Devil's advocacy
role.  It is true, most OS projects suffer from this, but only
from an outsider's point of view.  The people who develop the
stuff and use it all the time, DO NOT NEED DOCUMENTATION.
People who do not participate, DO.   So it is thus purely an exercise
in altruism on the developers' part.


Really, though, if there were just a central e-mail to send snippets
and paragraphs, I'm sure a lot of people like me would probably
enjoy sending in small submissions.



I remember about 18 months ago, I saw a posting with the subject:

Tomcat Documentation in Spanish

I assumed that the content of the message would be something like

"Where can I get it?"

but it was more like:

"I just did a translation, if anyone needs it"

I don't speak Spanish, so it had no direct benefit to me, but indirectly,
it was encouraging to see someone contributing their time and effort
freely like that, with no recompense at all except for a good feeling.

The Net in general needs less Q and more A,
less "???" and more "!!!", fewer remoras and more sharks.



Bob