cocoon-users mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Robin Green" <gree...@hotmail.com>
Subject Re: documentation
Date Fri, 02 Mar 2001 18:11:35 GMT
"tom" <tom@tnimmo.co.uk> wrote:
>I am new to this list and have been learning how to use Cocoon and Tomcat 
>after getting interested in XML.  I have had real problems with all the 
>documentation. Even Brett McLaughlin's book "Java and XML", which I bought, 
>seems out of date already

Correct.

>This means that days, even weeks are wasted just trying to piece together 
>enough information to get the basic tools up and running.
>I do not mean this as criticism:

If it's not criticism, I don't know what it is! ;) Perhaps you really mean 
"I do not mean this as a personal attack".

>preparing documentation is an enormous undertaking, especially doing it  
>for people who might have a very "limited" - perhaps non-existent ;) - 
>knowledge, and particularly when people preparing the documentation are so 
>familiar with platforms, standards, OSes, programming etc.
>
>The point I would like to make is that we need a new approach to 
>documentation preparation:
>
>1 the success of the "works out of the box" software brigade is precisely 
>because it installs when double-clicked!!

I agree. It would be nice to have this (and we _do_ now have this to a 
limited extent - RPMs for Tomcat/Apache on Linux, but they are very brittle 
IMO, and also too opaque for my liking).

But if someone had done this recently for Cocoon, Apache and Tomcat 3.1 
(only one of very many possible configurations), it would have been out of 
date and in need of updating within months, believe me. The same is probably 
true for Tomcat 3.2, etc.

At the moment the priorities of most Cocoon developers are directed toward 
getting Cocoon 2 to a release-quality state, because the new SAX and 
sitemap-based architecture and new codebase has so much potential. But 
anyone is welcome to submit suggestions and improvements to the installation 
procedure, whether code or documentation.

>it may not do much else, it will almost certainly adhere to proprietary 
>standards, but after the excruciatingly painful time I have had to get 
>Cocoon and Tomcat working, just on a laptop, it is obvious why people stick 
>with "out of the box" stuff;

I agree it can be painful - so let's try and make it better.

>I would like to help to find a way of improving the documentation so that 
>the tools are more accessible.

Good! The first step is to identify mistakes and problems, and then improve 
the code and/or documentation so as to try and avoid them.

You haven't specifically identified any mistakes or problems. Let's get down 
to specifics. I know it can sometimes be hard to remember the problems you 
encounter in sufficient detail, but how else can we improve it? Take notes 
if necessary.



_________________________________________________________________________
Get Your Private, Free E-mail from MSN Hotmail at http://www.hotmail.com.


Mime
View raw message