You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@tomcat.apache.org by Jon Stevens <jo...@latchkey.com> on 2001/01/05 23:43:16 UTC
Re: Tomcat documentation issue
on 1/5/2001 2:50 PM, "Paulo Gaspar" <pa...@krankikom.de> wrote:
> Well, that sure is part of many postings we see at the User lists.
> But the fact is that there are still to many beginner/configuration
> questions popping up that have no answer in any documentation.
Then write a FAQ and point people to it.
> It is a pity if the newbies are supposed to dig mail archives for
> ages when it would take much less energy to have placed those once
> written specs on the distribution.
Great. As Nike says: Just Do it.
> I have already seen on several Open Source products mailing lists,
> references to specifications written and approved before I signed
> those lists. And then (surprise, surprise!) I am not able to find
> them. Neither together with the distribution nor on the product's
> site.
What does that have to do with this project?
> It is a mystery to me what happens to those things!
Search the archives of the lists or ask the project leaders.
> Again, I am talking about reasonable documentation for people that
> want to learn and not about the unprecedented miracle of turning
> lazy dumb asses into geeks.
>
> Anyway, Open Source projects are very "green" about that: electronic
> documentation only!
> =:o)
What is reasonable to one is not reasonable to another. For example, reading
the source code is more than reasonable to me, but might not be as
reasonable to a newbie. The question then becomes: "Where do you draw the
line?"
My point being that you don't even have a piece of chalk to draw the line
with. :-)
> LOL
> Not so much effort to write the paragraph.
Not so much effort to write documentation.
> Anyway, the fact is that I still do not understand Tomcat well enough
> to do such thing. I'm getting there, but I still do not understand a
> couple of details - in any of the things I do with it.
Then ask on the list so that it is archived and people can look it up. Take
the responses and turn them into documentation.
-jon
Re: Tomcat documentation issue
Posted by Ted Husted <ne...@husted.com>.
I'll look forward to the FAQ-O-MATIC being fixed, at which time I will
happily contribute the many things I have been tucking away, while
fielding some of the easier questions on the User list.
I also hope that we can then open a Struts FAQ, so I can post what I
have put together at
< http://husted.com/about/struts/ >
Aside from some FAQs, I have also volunteered an extensive Struts
tutorial, based on the Example application, along with a new example
application, which demonstrates hooking Struts up to MySQL. With a
working FAQ-O-MATIC, it will be much easier for these volunteer
contributions to be made available to the rest of the community. I'm
glad that we can all work together toward a common goal.
"From each according to their ability, to each according to their
need."
Re: Tomcat documentation issue
Posted by Jon Stevens <jo...@latchkey.com>.
on 1/5/2001 9:58 PM, "Ted Husted" <ne...@husted.com> wrote:
> On 1/6/2001 at 3:58 AM Paulo Gaspar wrote:
>> Some of the things that Tomcat is said to support (like SSL,
> embedding and extending Tomcat) require a load of investigation FROM
> EACH PERSON that tries to use it because there is not even a good
> pointer on where to start digging.
>
> It would be helpful if the FAQ-O-MATIC actually worked; then those of
> us with a documentation itch could scratch in peace. But I'm told
> there's no ETA on that. As it stands, I just try to muddle through with
> my own Struts resource page at
>
> < http://husted.com/about/struts/ >
Well, the other day someone actually volunteered to make it work. They were
promptly given an account on the apache.org box with full access to what
they need to make it happen.
You could have volunteered.
-jon
RE: Tomcat documentation issue
Posted by Ted Husted <ne...@husted.com>.
On 1/6/2001 at 3:58 AM Paulo Gaspar wrote:
> Some of the things that Tomcat is said to support (like SSL,
embedding and extending Tomcat) require a load of investigation FROM
EACH PERSON that tries to use it because there is not even a good
pointer on where to start digging.
It would be helpful if the FAQ-O-MATIC actually worked; then those of
us with a documentation itch could scratch in peace. But I'm told
there's no ETA on that. As it stands, I just try to muddle through with
my own Struts resource page at
< http://husted.com/about/struts/ >
-- Ted Husted, Husted dot Com, Fairport NY USA.
-- Custom Software ~ Technical Services.
-- Tel 716 425-0252; Fax 716 223-2506.
-- http://www.husted.com/
RE: Tomcat documentation issue
Posted by Paulo Gaspar <pa...@krankikom.de>.
I am sure you are an happier man having the last word.
Have fun,
Paulo
> -----Original Message-----
> From: Jon Stevens [mailto:jon@latchkey.com]
> Sent: Saturday, January 06, 2001 04:57
>
> on 1/5/2001 8:00 PM, "Paulo Gaspar" <pa...@krankikom.de> wrote:
>
> > Community driven!
>
> Exactly. Other people have other itches.
>
> > You didn't?
>
> Nope.
>
> >> Like I said already. Suggestions are not helpful. It is like
> >> putting the job on someone else shoulders.
> >
> > Ist it? Am I doing that?
>
> Yes.
>
> > Ah... you do?
>
> Of course. The people on this list aren't idiots.
>
> > Am I? (Learning a lot tonight!)
>
> Yes.
>
> >> Wow. That is such a GREAT suggestion! I'm surprised that no
> one here would
> >> have ever though of such a mind blowing improvement!
> >
> > I am surprised too.
>
> I was being sarcastic.
>
> >> I will work
> >> as quickly
> >> as I can do go over all of the archives and implement exactly
> >> what you say!
> >
> > Then you missed the point:
> > - "at the right moment";
> > - "Turning such postings into documentation is something very easy to do
> > just at the time those texts are approved... and very hard afterwards".
>
> I was being sarcastic.
>
> > Much more "up to the task" than any Apache project I know of.
> > (But of course that it is a small project.)
>
> Uh. What exactly is lacking in Velocity's documentation? In fact, a good
> portion of it has been written by a professional author.
>
> <http://jakarta.apache.org/velocity/>
>
> >> You have this assumption that myself or other people on this list are
> >> supposed to jump up and suddenly take your earth shaking ideas
> >> and implement
> >> them. Not.
> >
> > Do I?
>
> Yep. It seems that way.
>
> > The project is good enough at what it does. And the docs too.
>
> I could say the same thing about Tomcat. It is all about perspective and
> level of education in the field.
>
> > Did I sound as mush "pushing" to you as you are sounding to me?
>
> Yes. Exactly.
>
> > Have fun (you realy need it),
>
> Thanks for telling me what I need.
>
> -jon
>
Re: Tomcat documentation issue
Posted by Jon Stevens <jo...@latchkey.com>.
on 1/5/2001 8:00 PM, "Paulo Gaspar" <pa...@krankikom.de> wrote:
> Community driven!
Exactly. Other people have other itches.
> You didn't?
Nope.
>> Like I said already. Suggestions are not helpful. It is like
>> putting the job on someone else shoulders.
>
> Ist it? Am I doing that?
Yes.
> Ah... you do?
Of course. The people on this list aren't idiots.
> Am I? (Learning a lot tonight!)
Yes.
>> Wow. That is such a GREAT suggestion! I'm surprised that no one here would
>> have ever though of such a mind blowing improvement!
>
> I am surprised too.
I was being sarcastic.
>> I will work
>> as quickly
>> as I can do go over all of the archives and implement exactly
>> what you say!
>
> Then you missed the point:
> - "at the right moment";
> - "Turning such postings into documentation is something very easy to do
> just at the time those texts are approved... and very hard afterwards".
I was being sarcastic.
> Much more "up to the task" than any Apache project I know of.
> (But of course that it is a small project.)
Uh. What exactly is lacking in Velocity's documentation? In fact, a good
portion of it has been written by a professional author.
<http://jakarta.apache.org/velocity/>
>> You have this assumption that myself or other people on this list are
>> supposed to jump up and suddenly take your earth shaking ideas
>> and implement
>> them. Not.
>
> Do I?
Yep. It seems that way.
> The project is good enough at what it does. And the docs too.
I could say the same thing about Tomcat. It is all about perspective and
level of education in the field.
> Did I sound as mush "pushing" to you as you are sounding to me?
Yes. Exactly.
> Have fun (you realy need it),
Thanks for telling me what I need.
-jon
RE: Tomcat documentation issue
Posted by Paulo Gaspar <pa...@krankikom.de>.
> -----Original Message-----
> From: Jon Stevens [mailto:jon@latchkey.com]
> Sent: Saturday, January 06, 2001 04:16
>
> Because it isn't my itch to scratch. The software works fine for me and I
> understand it perfectly well.
Community driven!
> I make time to correct. I haven't flamed you at all.
You didn't?
> You are just on the
> defensive over an email and someone you have never even met face to face.
> How weird is that.
As weird as the exhaustive answer... but point taken.
> I'm simply having a conversation.
Sure.
> Like I said already. Suggestions are not helpful. It is like
> putting the job on someone else shoulders.
Ist it? Am I doing that?
> Telling us that we need more documentation isn't anything that we don't
> already know. Duh.
Ah... you do?
> > Notice that I am not demanding this or that. I am aware that Tomcat
> > is (mostly) volunteer work.
>
> Ah. But you are demanding.
Am I? (Learning a lot tonight!)
> You are saying things like:
> > Tomcat has the same problem as Struts and most Open Source
> > projects (it is not just an Apache thing):
> > * NOT ENOUGH DOCUMENTATION *
>
> In case you missed it UPPERCASE and ** is like yelling at us
> saying that we
> need more documentation.
>
> If you had said something like:
>
> "The Tomcat project needs documentation in the following areas: blah blah
> blah."
If you found the Uppercase, I am sure you can find the areas I mentioned
too.
> > It is not even something fancy - just remembering to spend some extra
> > 5 minutes of effort at the right moment:
> > - I suggested turning project specs and proposals that are posted
> > here (and in other Apache projects) into documentation in the
> > distribution (of this and those other projects).
>
> Wow. That is such a GREAT suggestion! I'm surprised that no one here would
> have ever though of such a mind blowing improvement!
I am surprised too.
> I will work
> as quickly
> as I can do go over all of the archives and implement exactly
> what you say!
Then you missed the point:
- "at the right moment";
- "Turning such postings into documentation is something very easy to do
just at the time those texts are approved... and very hard afterwards".
> > I am not even asking great documentation as FreeMarker has (and it is
> > GPL). Just posts turned into documents with basic editing.
>
> Lol. I thought FM's documented sucked.
Much more "up to the task" than any Apache project I know of.
(But of course that it is a small project.)
> You have this assumption that myself or other people on this list are
> supposed to jump up and suddenly take your earth shaking ideas
> and implement
> them. Not.
Do I?
> > Do you want to draw a line on what is good documentation?
> > Look at FreeMarker. Doesn't even have to look so nice.
>
> That documentation sucks and the project is dead. What is to envy about
> that?
The project is good enough at what it does. And the docs too.
> Yep. Sucks doesn't it? Why don't you contribute some documentation to help
> improve it?
Is it my turn to jump and do what you say.
Did I sound as mush "pushing" to you as you are sounding to me?
Ok, had enough.
Have fun (you realy need it),
Paulo
Re: Tomcat documentation issue
Posted by Jon Stevens <jo...@latchkey.com>.
on 1/5/2001 6:58 PM, "Paulo Gaspar" <pa...@krankikom.de> wrote:
> Why do I have the feeling you are always "against"?
> Is "being constructive" OUT?
Is making suggestions for work for other people to do considered being
constructive? In a volunteer organization, I don't think so.
> Why don't YOU do that documentation work?
> - Are you busy?
> - Have other priorities?
Because it isn't my itch to scratch. The software works fine for me and I
understand it perfectly well.
> Guess what: me too! We both have that same problem, but:
> - I still make time for some suggestions;
Well defined proposals are helpful (fyi, someone is working on the
mod_rewrite module for Tomcat)
Code is helpful.
Suggestions aren't helpful.
> - You still make time to flame everybody!
I make time to correct. I haven't flamed you at all. You are just on the
defensive over an email and someone you have never even met face to face.
How weird is that.
I'm simply having a conversation.
> I don't have to, but since you displayed so much concern about the
> way I spend my time, I am going to tell you what my priorities are.
To bad you didn't just spend your time documenting things. :-( I could care
diddly about your priorities as I'm sure you could care diddly about mine.
:-)
> For me, at the moment, it makes much more sense to invest on Taglibs
> and possibly Struts:
> - it is what I see serving better the current needs of my employer;
> - it is what I can do faster and where I can be more productive;
> - it makes sense to contribute them to Jakarta afterwards and my
> managers will possibly agree with that.
Good for you!
> Does this prevent me from defending or suggesting things that can
> turn Tomcat into something better for me and others?
Like I said already. Suggestions are not helpful. It is like putting the job
on someone else shoulders.
Telling us that we need more documentation isn't anything that we don't
already know. Duh.
> (And, for me, the documentation is no longer a big problem.)
Good, so you have a good understanding of things. Then take that and
document it for others.
> Notice that I am not demanding this or that. I am aware that Tomcat
> is (mostly) volunteer work.
Ah. But you are demanding. You are saying things like:
> Tomcat has the same problem as Struts and most Open Source
> projects (it is not just an Apache thing):
> * NOT ENOUGH DOCUMENTATION *
In case you missed it UPPERCASE and ** is like yelling at us saying that we
need more documentation.
If you had said something like:
"The Tomcat project needs documentation in the following areas: blah blah
blah."
And then taken the time to actually list those areas and maybe even start a
table of contents, as a html page, then, that would have been helpful. We
could have checked that into CVS and let people start to fill out the
missing areas as needed.
But simply stating * NOT ENOUGH DOCUMENTATION * is totally worthless and
degenerative to the people who work on this project.
> But is it bad that I post constructive suggestions?
It wasn't constructive. You simply ranted on about how we don't have any
documentation and how newbies need more documentation. What is constructive
about that?
> If documentation could be improved a bit, without much effort and
> just a hint of method, then why not?
I agree. Give a hint.
> It is not even something fancy - just remembering to spend some extra
> 5 minutes of effort at the right moment:
> - I suggested turning project specs and proposals that are posted
> here (and in other Apache projects) into documentation in the
> distribution (of this and those other projects).
Wow. That is such a GREAT suggestion! I'm surprised that no one here would
have ever though of such a mind blowing improvement! I will work as quickly
as I can do go over all of the archives and implement exactly what you say!
Would that have been a better response?
> I am not even asking great documentation as FreeMarker has (and it is
> GPL). Just posts turned into documents with basic editing.
Lol. I thought FM's documented sucked.
> Why doesn't this make sense to you?
Cause you didn't even state that the first time. Why doesn't that make sense
to you? :-)
> Don't you notice Tomcat documentation problems? How can you defend
> that someone should read the code to understand how to configure
> something?
I know all about them, but like I said. I don't have the itch. You seem to
do though.
You have this assumption that myself or other people on this list are
supposed to jump up and suddenly take your earth shaking ideas and implement
them. Not.
> Do you want to draw a line on what is good documentation?
> Look at FreeMarker. Doesn't even have to look so nice.
That documentation sucks and the project is dead. What is to envy about
that?
> Some of the things that Tomcat is said to support (like SSL, embedding
> and extending Tomcat) require a load of investigation FROM EACH PERSON
> that tries to use it because there is not even a good pointer on where
> to start digging.
Yep. Sucks doesn't it? Why don't you contribute some documentation to help
improve it?
> And now, the three hopes I have for you:
> 1. I hope you can still see the value of plain English after all that
> heavy source code reading;
Given that english is my only language...
> 2. I hope that you can still respect newbies - that you didn't
> already forget that you were once one;
I don't respect people who expect to be spoon fed.
> 3. I hope that this is not a revenge - that you do not want others to
> learn things the hard way just because you did so.
Definitely not.
> I am learning the hard way for (already!) a bit more than a decade
> and I keep trying to ease the way to others. Since you are on Open
> Source for longer than me and you are supposed to know the culture
> better, I am going to ask you:
> - Am I wrong?
Yes.
> - Do you thing I should say "Read the fucking source code!!!" to
> anybody that asks me about the open source stuff we use?
No. I will repeat it all one more time:
You have an itch. Scratch it.
Suggestions about the obvious are worthless. We already know the problems.
Code is useful.
Documentation is useful.
Contributions are appreciated.
Please don't respond again unless it is documented.
-jon
RE: Tomcat documentation issue
Posted by Paulo Gaspar <pa...@krankikom.de>.
Jon,
Why do I have the feeling you are always "against"?
Is "being constructive" OUT?
Why don't YOU do that documentation work?
- Are you busy?
- Have other priorities?
Guess what: me too! We both have that same problem, but:
- I still make time for some suggestions;
- You still make time to flame everybody!
I don't have to, but since you displayed so much concern about the
way I spend my time, I am going to tell you what my priorities are.
For me, at the moment, it makes much more sense to invest on Taglibs
and possibly Struts:
- it is what I see serving better the current needs of my employer;
- it is what I can do faster and where I can be more productive;
- it makes sense to contribute them to Jakarta afterwards and my
managers will possibly agree with that.
Does this prevent me from defending or suggesting things that can
turn Tomcat into something better for me and others?
(And, for me, the documentation is no longer a big problem.)
Notice that I am not demanding this or that. I am aware that Tomcat
is (mostly) volunteer work.
But is it bad that I post constructive suggestions?
If documentation could be improved a bit, without much effort and
just a hint of method, then why not?
It is not even something fancy - just remembering to spend some extra
5 minutes of effort at the right moment:
- I suggested turning project specs and proposals that are posted
here (and in other Apache projects) into documentation in the
distribution (of this and those other projects).
Turning such postings into documentation is something very easy to do
just at the time those texts are approved... and very hard afterwards.
Even if they are not well organized, it is much better to search what
you need from a not so big list of useful documents than from a huge
mailing list archive with a lot of "noise".
I am not even asking great documentation as FreeMarker has (and it is
GPL). Just posts turned into documents with basic editing.
Why doesn't this make sense to you?
Don't you notice Tomcat documentation problems? How can you defend
that someone should read the code to understand how to configure
something?
Do you want to draw a line on what is good documentation?
Look at FreeMarker. Doesn't even have to look so nice.
Some of the things that Tomcat is said to support (like SSL, embedding
and extending Tomcat) require a load of investigation FROM EACH PERSON
that tries to use it because there is not even a good pointer on where
to start digging.
And now, the three hopes I have for you:
1. I hope you can still see the value of plain English after all that
heavy source code reading;
2. I hope that you can still respect newbies - that you didn't
already forget that you were once one;
3. I hope that this is not a revenge - that you do not want others to
learn things the hard way just because you did so.
I am learning the hard way for (already!) a bit more than a decade
and I keep trying to ease the way to others. Since you are on Open
Source for longer than me and you are supposed to know the culture
better, I am going to ask you:
- Am I wrong?
- Do you thing I should say "Read the fucking source code!!!" to
anybody that asks me about the open source stuff we use?
Have some fun,
Paulo Gaspar
> -----Original Message-----
> From: Jon Stevens [mailto:jon@latchkey.com]
> Sent: Friday, January 05, 2001 23:43
>
> on 1/5/2001 2:50 PM, "Paulo Gaspar" <pa...@krankikom.de> wrote:
>
> > I have already seen on several Open Source products mailing lists,
> > references to specifications written and approved before I signed
> > those lists. And then (surprise, surprise!) I am not able to find
> > them. Neither together with the distribution nor on the product's
> > site.
>
> What does that have to do with this project?
>
> > It is a mystery to me what happens to those things!
>
> Search the archives of the lists or ask the project leaders.
>
> > Again, I am talking about reasonable documentation for people that
> > want to learn and not about the unprecedented miracle of turning
> > lazy dumb asses into geeks.
> >
> > Anyway, Open Source projects are very "green" about that: electronic
> > documentation only!
> > =:o)
>
> What is reasonable to one is not reasonable to another. For
> example, reading
> the source code is more than reasonable to me, but might not be as
> reasonable to a newbie. The question then becomes: "Where do you draw the
> line?"
>
> My point being that you don't even have a piece of chalk to draw the line
> with. :-)
>