Please read....

[Martin Koistinen <ma...@koistinen.com>]

Hi all.

I was going to post a long message describing in painful detail the 4 hours 
I spent trying to install Apache+Tomcat from scratch as a DSO.

Then, after I finally got it working I realized that I was so ignorant on 
many things that I you all would think I was a complete moron.  But, now, 
in retrospect, I value the perspective as me as a newbie and would like to 
offer some advice and perhaps some time to the effort.  As a newbie, I did 
NOT understand the relationship between JServ and Jakarta and Tomcat -- in 
fact, I don't think I do now even though I managed to get it all 
working.  This is an important part of the installation process since 
troubleshooting begins with understanding.

As a newbie it was very frustrating NOT having a link from the main page of 
jakarta.apache.org that told me the relationships between the different 
pieces of software and exactly which of what I needed to make this work 
(with accurate links to them).  It was frustrating not having an accurate, 
up-to-date set of instructions that I could read to make this clearer.  It 
was frustrating that the documentation I did find is in error in key places.

SUGGESTIONS:
* make a documentation link on the main page of jakarta.apache.org that 
points to, if nothing else, the APACHE+TOMCAT HOWTO (fix it first).

* Ideally, it would start out with a description of the required components 
and then some brief discussion about what they are/do and then describe the 
different ways to get JServ/Tomcat working on your system (DSO vs static, 
w/apache vs standalone, etc.)

* Perhaps some links to instructions on how to use it once you've decided 
what is best for you.

* Correct the documentation that is in error.
         In the HOWTO mentioned above, there should be mention of actually 
starting the server before you test it.
         Also, the HOWTO points to URLs for downloading the various pieces 
that are wrong:

 From the HOWTO:
>        * Download and install Tomcat 3.0 for your OS/platform from
>         http://jakarta.apache.org/builds/tomcat/release/v3.0/<os>/<platform>
>        * Download mod_jserv for your platform from
> 
>http://jakarta.apache.org/builds/tomcat/release/v3.0/<os>/<platform>/modules

         There is no modules directory and instead the mod_jerv.so file was 
at the other location.  There was no installation for tomcat in here at all 
(at least for linux/i386 on Feb 21st, 2000)

I would be happy to do some of this work but I lack the knowledge of the 
project (and I'm not that good of a writer either).  However, I'd be happy 
to HTML-smith some information and perhaps provide some structure to it for 
placement on the site where it belongs.  Letting the faq'o'matic and random 
users create the "official" documentation is probably a bad idea since the 
result would lack consistency (in terminology and style), accuracy, 
accountability and maintainability.  There needs to be an official 
documentation process.

I hope this is more helpful then not.
-- Martin Koistinen

Re: Please read....

[William Wise <wi...@digitalelite.com>]

I agree with this.  I'm not a newbie but was one and understand Martin's
situation.  Yes, I sometimes enjoy the challenge a 5-age install document
culled from 3 different (sometime conflicting) sources presents.  It's a
good feeling knowing you're a 7th level Linux Ninja!  :-)  But, when you you
start to use the software in a business environment with deadlines, bosses
breathing down your neck looking for results, etc... its no fun at all.

The counter-balancing issue is that beta software is understandably not well
documented as it is a state of flux.  Still, who wants to find themselves
0/5 on an install when it is obvious that the knowledge is out there to
avoid this.

This is especially important for open-source projects where potential
collaborators would rather be coding to their interests and contributing to
the project rather than wasting days or weeks trying to install and
configure the base product.

Just my 2-cents.  I think we can do better than this.

Will

PS:  This line of reasoning is spilling over from the JetSpeed project
discussion list but I think it is relevant here as well.

----- Original Message -----
From: "Martin Koistinen" <ma...@koistinen.com>
To: <ge...@jakarta.apache.org>
Sent: Monday, February 21, 2000 11:02 PM
Subject: Please read....


> Hi all.
>
> I was going to post a long message describing in painful detail the 4
hours
> I spent trying to install Apache+Tomcat from scratch as a DSO.
>
> Then, after I finally got it working I realized that I was so ignorant on
> many things that I you all would think I was a complete moron.  But, now,
> in retrospect, I value the perspective as me as a newbie and would like to
> offer some advice and perhaps some time to the effort.  As a newbie, I did
> NOT understand the relationship between JServ and Jakarta and Tomcat -- in
> fact, I don't think I do now even though I managed to get it all
> working.  This is an important part of the installation process since
> troubleshooting begins with understanding.
>
> As a newbie it was very frustrating NOT having a link from the main page
of
> jakarta.apache.org that told me the relationships between the different
> pieces of software and exactly which of what I needed to make this work
> (with accurate links to them).  It was frustrating not having an accurate,
> up-to-date set of instructions that I could read to make this clearer.  It
> was frustrating that the documentation I did find is in error in key
places.
>
> SUGGESTIONS:
> * make a documentation link on the main page of jakarta.apache.org that
> points to, if nothing else, the APACHE+TOMCAT HOWTO (fix it first).
>
> * Ideally, it would start out with a description of the required
components
> and then some brief discussion about what they are/do and then describe
the
> different ways to get JServ/Tomcat working on your system (DSO vs static,
> w/apache vs standalone, etc.)
>
> * Perhaps some links to instructions on how to use it once you've decided
> what is best for you.
>
> * Correct the documentation that is in error.
>          In the HOWTO mentioned above, there should be mention of actually
> starting the server before you test it.
>          Also, the HOWTO points to URLs for downloading the various pieces
> that are wrong:
>
>  From the HOWTO:
> >        * Download and install Tomcat 3.0 for your OS/platform from
> >
http://jakarta.apache.org/builds/tomcat/release/v3.0/<os>/<platform>
> >        * Download mod_jserv for your platform from
> >
>
>http://jakarta.apache.org/builds/tomcat/release/v3.0/<os>/<platform>/module
s
>
>          There is no modules directory and instead the mod_jerv.so file
was
> at the other location.  There was no installation for tomcat in here at
all
> (at least for linux/i386 on Feb 21st, 2000)
>
> I would be happy to do some of this work but I lack the knowledge of the
> project (and I'm not that good of a writer either).  However, I'd be happy
> to HTML-smith some information and perhaps provide some structure to it
for
> placement on the site where it belongs.  Letting the faq'o'matic and
random
> users create the "official" documentation is probably a bad idea since the
> result would lack consistency (in terminology and style), accuracy,
> accountability and maintainability.  There needs to be an official
> documentation process.
>
> I hope this is more helpful then not.
> -- Martin Koistinen
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: general-unsubscribe@jakarta.apache.org
> For additional commands, e-mail: general-help@jakarta.apache.org
>