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
went".
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
>
>
Craig
