You are viewing a plain text version of this content. The canonical link for it is here.
Posted to users@tomcat.apache.org by GOMEZ Henri <hg...@slib.fr> on 2001/06/29 22:10:49 UTC
[PRE-PROPOSAL] jakarta-tomcat-doc sub-project : WAS: [Tomcat Docu
mentation Redactors To Hire]
>Hi Henri!
>
>One suggestion: create a mailing list (e.g. tomcat-doc) so that folks
>may speak about docs. Also, it would show some level of
>commitment -- at
>least you have to subscribe.
Good idea,
We could have a tomcat-doc mailing-list, but we'll still
need to commit the material.
And currently when you update documentation, you could have
2 or 3 branchs to updates (TC 3.2, 3.3, 4.0).
But there is many common areas (realms, connectors) and
we should avoid such duplication effort...
What about starting a jakarta-tomcat-doc sub-project, where
some redactors could have commit access, maybe even without
commit access to developpers projects like tomcat, j-t-c, jasper...
A quick proposal of tree could be :
jakarta-tomcat-doc + +- jserv
| |
+- connectors -+- jk
| |
| +- webapp
|
+- jasper (3.2/3.3)
|
+- realms (JDBC/JNDI/LDAP)
|
+- tomcat 3.x
|
+- tomcat 4.x
For example, when I wrote documentation, my main problem is HTML,
not writing documentation.
XML/XSL should help us here and we could use tools Jon deployed for
jakarta site or may a better base could be DOCBOOK.
I take a look at the current tomcat-book site at sourceforge,
and found there excellent materials to be use, and they use DOCBOOK
I'm sure we could find motivated users for that job, some will not
be developpers but excellent redactors. They may be afraid having
a commit access to a developpement tree but if restricted to
documentation sub-project...
And it will help, us, developpers since as you all know Redactor
(or managers :) want clear explanations. We must do an effort there
to explain clearly, concept, design, implementations and configuration,
and that help back the developpers detecting mistakes.
We all know that the weakest point in Tomcat is its documentation,
if we succeed in that area, we'll gain :
- Reducing the number of beginers question on tomcat-user list.
- Converting some beginers to later power-users and may be contributors
- ....
I've got an example of a great documentation which converted
many users, mod_ssl. As many of you, when I needed SSL support for
Apache, I asked Apache gurus as which recommanded Apache/SSL written
by Ben Laurie, a known specialist in Apache HTTP.
I try it, find it fast, reliable but poorly documented (sorry Ben).
I then discovered mod_ssl, written by a another code wizard,
Ralf Engelschall. I tried mod_ssl and found it as stable and
fast than Apache/SSL. Then I take a serious look at the documentation
found at its home, http://www.modssl.org and also included in distrib.
And that make me switch definitly to mod_ssl.
There is many others great servlet-engine around, and not all
are commercials products.
Apache HTTPD server reputation and Apache JServ quality have helped
Tomcat to be in general the first servlet-engine tried by beginers.
If we want to keep them, we must have a stable and fast Tomcat,
but first we must make Tomcat easy to understand, configure and
use.
* Having an easy to run tomcat, was one of the reason I started
to package tomcat RPMs. And I have very little questions
from beginers on how to use tomcat on their Linux Box...
* One of the most common problem for new users, is the
connection with their web-server, and that's why I asked many
times to have a connector sub-project.
That project, jakarta-tomcat-connector, has started recently.
In J-T-C, JF Clere show how easy could be a build process of
even the <dreaded> mod_jk.
On the configure side, I started Ajp14 to help users have
an easy way configuring their web-server, with informations
caming from servlet-engine (which URIs & MIMES handled) ....
We need a the same level of quality in documentation that in
code itself....
My 0.1 EUR
Re: [PRE-PROPOSAL] jakarta-tomcat-doc sub-project : WAS: [Tomcat Documentation Redactors To Hire]
Posted by Punky Tse <pu...@yahoo.com>.
See comments below.
> And currently when you update documentation, you could have
> 2 or 3 branchs to updates (TC 3.2, 3.3, 4.0).
>
> But there is many common areas (realms, connectors) and
> we should avoid such duplication effort...
>
> What about starting a jakarta-tomcat-doc sub-project, where
> some redactors could have commit access, maybe even without
> commit access to developpers projects like tomcat, j-t-c, jasper...
>
> A quick proposal of tree could be :
>
> jakarta-tomcat-doc + +- jserv
> | |
> +- connectors -+- jk
> | |
> | +- webapp
> |
> +- jasper (3.2/3.3)
> |
> +- realms (JDBC/JNDI/LDAP)
> |
> +- tomcat 3.x
> |
> +- tomcat 4.x
>
I would like to have another suggestion. The jakarta-tomcat-doc repository
should only contains a complete handbook for various tomcat servers (3.2,
3.3 & 4.0). The handbook should covers sections like Installation, System
Adminstration, Webapp development and Performance Tuning. (uh, I copy it
from FreeBSD handbook). Also, a separate developer handbook can be written
as needed.
For specifications and technical notes (for example WARP spec), because it
documents the developer mind and serves as an effective commuication for
developers, I still suggest leaving them in the original repository. For
how-tos (JDBC/Realms, connectors), I think we just have to compile an index
for it.
Just my 2 cents.
Punky
Re: [PRE-PROPOSAL] jakarta-tomcat-doc sub-project : WAS: [Tomcat Docu mentation Redactors To Hire]
Posted by Frans Thamura <ft...@yahoo.com>.
Great I like that mailing list..
Idea,
I don't care if there is DOCBOOK or HTML, or I
prefered a database driven, and that database will be
a DOCBOOK.. so we need DB -> DOCBOOK. Think like a
content management software, yah, we can make like
phpNUKE.
you have to put :
0. Installation Guide
1. getting started document.
Basic step-by-step instruction, so a new user can use
tomcat.
2. User Guide.
3. How it work, a conceptual to implementation
like why .war will be unzipped automatically???
4. Last Proposal
5. Working Document
6. Final Document
7. FAQ (I prefere a forum in apache.org, why don't you
try phorum.org)
So a new user can use read that, may be one of them
can be a redactor or commiter in the overdrive
velocity..
Frans Thamura
--- GOMEZ Henri <hg...@slib.fr> wrote:
> >Hi Henri!
> >
> >One suggestion: create a mailing list (e.g.
> tomcat-doc) so that folks
> >may speak about docs. Also, it would show some
> level of
> >commitment -- at
> >least you have to subscribe.
>
> Good idea,
>
> We could have a tomcat-doc mailing-list, but we'll
> still
> need to commit the material.
>
> And currently when you update documentation, you
> could have
> 2 or 3 branchs to updates (TC 3.2, 3.3, 4.0).
>
> But there is many common areas (realms, connectors)
> and
> we should avoid such duplication effort...
>
> What about starting a jakarta-tomcat-doc
> sub-project, where
> some redactors could have commit access, maybe even
> without
> commit access to developpers projects like tomcat,
> j-t-c, jasper...
>
> A quick proposal of tree could be :
>
> jakarta-tomcat-doc + +- jserv
> | |
> +- connectors -+- jk
> | |
> | +- webapp
> |
> +- jasper (3.2/3.3)
> |
> +- realms (JDBC/JNDI/LDAP)
> |
> +- tomcat 3.x
> |
> +- tomcat 4.x
>
>
> For example, when I wrote documentation, my main
> problem is HTML,
> not writing documentation.
> XML/XSL should help us here and we could use tools
> Jon deployed for
> jakarta site or may a better base could be DOCBOOK.
>
> I take a look at the current tomcat-book site at
> sourceforge,
> and found there excellent materials to be use, and
> they use DOCBOOK
>
> I'm sure we could find motivated users for that job,
> some will not
> be developpers but excellent redactors. They may be
> afraid having
> a commit access to a developpement tree but if
> restricted to
> documentation sub-project...
>
> And it will help, us, developpers since as you all
> know Redactor
> (or managers :) want clear explanations. We must do
> an effort there
> to explain clearly, concept, design, implementations
> and configuration,
> and that help back the developpers detecting
> mistakes.
>
> We all know that the weakest point in Tomcat is its
> documentation,
> if we succeed in that area, we'll gain :
>
> - Reducing the number of beginers question on
> tomcat-user list.
> - Converting some beginers to later power-users and
> may be contributors
> - ....
>
> I've got an example of a great documentation which
> converted
> many users, mod_ssl. As many of you, when I needed
> SSL support for
> Apache, I asked Apache gurus as which recommanded
> Apache/SSL written
> by Ben Laurie, a known specialist in Apache HTTP.
> I try it, find it fast, reliable but poorly
> documented (sorry Ben).
>
> I then discovered mod_ssl, written by a another code
> wizard,
> Ralf Engelschall. I tried mod_ssl and found it as
> stable and
> fast than Apache/SSL. Then I take a serious look at
> the documentation
> found at its home, http://www.modssl.org and also
> included in distrib.
> And that make me switch definitly to mod_ssl.
>
> There is many others great servlet-engine around,
> and not all
> are commercials products.
>
> Apache HTTPD server reputation and Apache JServ
> quality have helped
> Tomcat to be in general the first servlet-engine
> tried by beginers.
>
> If we want to keep them, we must have a stable and
> fast Tomcat,
> but first we must make Tomcat easy to understand,
> configure and
> use.
>
>
> * Having an easy to run tomcat, was one of the
> reason I started
> to package tomcat RPMs. And I have very little
> questions
> from beginers on how to use tomcat on their Linux
> Box...
>
> * One of the most common problem for new users, is
> the
> connection with their web-server, and that's why I
> asked many
> times to have a connector sub-project.
> That project, jakarta-tomcat-connector, has
> started recently.
> In J-T-C, JF Clere show how easy could be a build
> process of
> even the <dreaded> mod_jk.
> On the configure side, I started Ajp14 to help
> users have
> an easy way configuring their web-server, with
> informations
> caming from servlet-engine (which URIs & MIMES
> handled) ....
>
> We need a the same level of quality in documentation
> that in
> code itself....
>
> My 0.1 EUR
>
>
__________________________________________________
Do You Yahoo!?
Get personalized email addresses from Yahoo! Mail
http://personal.mail.yahoo.com/
Re: [PRE-PROPOSAL] jakarta-tomcat-doc sub-project : WAS: [Tomcat
Docu mentation Redactors To Hire]
Posted by "Pier P. Fumagalli" <pi...@betaversion.org>.
GOMEZ Henri at hgomez@slib.fr wrote:
>
> Good idea,
>
> We could have a tomcat-doc mailing-list, but we'll still
> need to commit the material.
I'd rather keep the documentation together with the project. When I
(don't :) write the docs, I don't want to update two CVSes, we can give
access to whoever wants to write it...
Pier