On Sat, 7 Jul 2001, Aaron Bannert wrote:
> 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/ :)
>
Sorry about that ... too many "A-list" people today :-)
> 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...)
>
It definitely makes sense to have enough "how to get started" stuff in
plain text README form to get a newbie going.
Hmm, if we can transform XML->HTML, maybe we can just use a different
stylesheet (or set of Anakia macros) and transform XML->TXT as well .....
>
> 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.
>
As a side comment on this topic, Tomcat 4 installation and administration
is going to directly benefit from Sun's JavaOne announcement about the Web
Services Pack (which will include Tomcat). In particular, my team at Sun
is going to put some serious developer hours into these areas, and the
vast majority of the resulting code will work just fine for a stand-alone
download of Tomcat from Apache as well.
By the way, one of the current XML docs
(catalina/docs/dev/xdocs/fs-admin-apps.xml) is a proposed set of high
level functional requirements for administrative apps for Tomcat 4.
Developers interested in this topic are encouraged to read it and
suggest improvements.
Sun is also increasing the number of folks writing and executing tests of
Tomcat 4 features (beyond the issues of spec compliance). In order to do
this, the test writers need a description of what correct behavior is --
so one of the things I will personally be working on is "functional
specs" type docs for the various existing features (such as the fs-*.xml
files in the same directory as the admin apps doc). That's why I'm quite
happy to see a discussion about documentation formats and tools happen
now. The net result will be a substantial increase in the amount of
useful "internals" documentation about how Tomcat 4 is put together.
> -aaron
>
>
Craig
