On Sat, Jul 07, 2001 at 09:25:46AM -0700, Craig R. McClanahan wrote:
> Yes, we obviously need pointers in a top-level README on "where the docs
> went".
I'm willing to collaborate on these types of docs. On a slight tangent,
I'd like to point out that we could use more STATUS and README documents,
if only to serve the purpose of a signpost for current and new developers.
*Every* CVS module that is a work-in-progress should have some sort of
STATUS document, as well as a README describing what the repository
contains. The first serves as a road map for any new developers who
want to get into the source. The second serves as a roadmap for new
builders/testers who want to know what the heck they're looking at.
> Also, on my list of "high level" desires, I forgot to include one:
>
> * All of the Tomcat documentation should be visible online at the Tomcat
> web site.
>
> which can (at least partially) deal with Alex's "how do you set up the
> VCR" issue :-).
( s/Alex/Aaron/ :)
That will partially satisfy me, but not everyone has fully-connected
high-speed internet access and graphical browsers (at least not while
they're trying to get Tomcat working). I'd still like to push for plain
text documentation for each of the following:
0) README and STATUS in each of
a) jakarta-tomcat-4.0
b) jakarta-regexp
c) jakarta-servletapi-4
d) jakarta-tomcat-connectors (* Pier is working on this, I've submitted
the beginnings of a README)
e) "the various TC3.x repositories that I'm less familiar with"
1) build instructions for each. Not extensive, just simple bootstrapping
instructions, maybe even just in the README.
2) [basic] configuration instructions. Again, not extensive, but enough
to get it up. Maybe a recipe that would answer questions like:
a) What goes in server.xml?
b) How do I start/stop TC?
c) What must be already installed in order to run TC? (JDK version, etc...)
Who's with me on this? I can submit an outline for each and let the people
with more experience fill in the blanks.
> > 2) Why have the docs as a web app? I'm not sure I see the benefits yet,
> > aside from being able to have a pointer to the docs from the ROOT/index
> > page.
> >
>
> A couple of reasons:
>
> * Because we already do -- and it's quite convenient to be able to
> look at the docs once you get Tomcat started the first time. The
> problem today is that we are really overloading the ROOT web app,
> and it's not particularly well organized.
I totally agree that it is convenient, but it may be harder for us to
realize the difficulty in getting this beast rolling the first time
from our altitude. We want every college student who has ever had any
interest in Servlets/JSP running this thing on their home Linux/*BSD/WinXX
(*gag*) machine, and they're only going to do that if the barrier to
entry is well defined.
-aaron
