tomcat-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Craig R. McClanahan" <>
Subject RE: [PRE-PROPOSAL] jakarta-tomcat-doc sub-project : WAS: [TomcatDocu mentation Redactors To Hire]
Date Sat, 07 Jul 2001 16:25:46 GMT

On Sat, 7 Jul 2001, Rob S. wrote:

> > Providing Tomcat documentation in a WAR file is a little like providing
> > a VHS tape on how to setup your VCR. It may seem really elegant to have
> > on-the-fly style-generating documentation, and I may be alone on this,
> > but I think that the majority of the user-oriented documentation should
> > just be plain text. (By 'user-oriented documentation' I specifically
> > mean build instructions and deployment configuration docs).
> It would be in a WAR file as HTML.  The build would do the transformation
> and create the WAR file.
> Two things:
> 1) Users may be confused as to "where the docs went" if they don't see a
> /docs directory.  Solution (one of many): have /docs/readme.txt with a
> pointer back to /INSTALL.txt.  A quick-install guide would be pretty
> short...

Yes, we obviously need pointers in a top-level README on "where the docs

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 :-).

> 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.

* Implicitly, I think we've been agreeing that the *output* format is
  HTML.  Using plain text just doesn't cut it when you want to create
  links to other portions of the docs, or include images beyond what
  you can do in ASCII art.  In essence, a web app is just a documentation
  directory with a little extra stuff (WEB-INF/*) that is not really much
  different than any other project that chooses HTML format for its docs.
  It's just in "webapps/docs" instead of "docs" in the binary distro.

> - r


View raw message