Return-Path: Mailing-List: contact tomcat-user-help@jakarta.apache.org; run by ezmlm Delivered-To: mailing list tomcat-user@jakarta.apache.org Received: (qmail 23914 invoked from network); 1 Mar 2001 19:59:58 -0000 Received: from hinge3.mistral.co.uk (195.184.228.58) by h31.sny.collab.net with SMTP; 1 Mar 2001 19:59:58 -0000 Received: from sr011786669 (d224-78.dial.mistral.co.uk [195.184.224.78]) by hinge3.mistral.co.uk (8.9.3/8.9.3) with SMTP id TAA22151 for ; Thu, 1 Mar 2001 19:59:57 GMT Message-ID: <006c01c0a289$e39b5100$4ee0b8c3@sr011786669> From: "tom" To: Subject: documentation Date: Thu, 1 Mar 2001 19:57:46 -0000 MIME-Version: 1.0 Content-Type: multipart/alternative; boundary="----=_NextPart_000_0067_01C0A289.E2FB1960" X-Priority: 3 X-MSMail-Priority: Normal X-Mailer: Microsoft Outlook Express 5.50.4133.2400 X-MimeOLE: Produced By Microsoft MimeOLE V5.50.4133.2400 X-Spam-Rating: h31.sny.collab.net 1.6.2 0/1000/N ------=_NextPart_000_0067_01C0A289.E2FB1960 Content-Type: text/plain; charset="iso-8859-1" Content-Transfer-Encoding: quoted-printable Hi all, 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 - and the instructions do not = work (at least not when I try them). 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: 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!! 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; 2 IMHO a new publishing framework will only truly succeed when = non-programmers etc like myself can access the new tools in a less = painful way, gain familiarity with them and think of things to do with = them - this might result in tools being used in ways that are less = dominated by the IT industries various mentalities, and mean that = Standards that are set (by eg W3C) prevail in the longer term; 3 the success of open source depends upon people with limited computer = skills being able to specify and use open source tools in their = projects, work etc. without having to run to their sysadmins, = programmers etc every five minutes over what are, to the experienced, = ridiculously simple problems; 4 there is also a problem with accessibility: many people use dial-up to = access the internet; in a lot of countries, as here in the UK, that = dial-up is not free of charge - this means that to spend hours trying to = piece together the various, inconsistent sources of documentation, even = the archives, to try and get a picture of how to get something up and = running is so full of frustration and so expensive, that having "played" = around for a while you just retreat and look at the old, proprietary = ways of doing things; These problems are not unique to this project, I have found it before - = also with proprietary packages - as I am sure we all have. However, = just as the internetworked world does not belong only to the corporates, = neither does it belong only to people who are computer or software = experts. The success of proprietary standards is not because people are = lazy, but because alternative tools are so inaccessible. I would like to help to find a way of improving the documentation so = that the tools are more accessible.=20 I repeat that this is not a criticism - documentation is a large task = and who wants to do that when they are brilliant software engineers at = the cutting edge ;) !! and have so little time. I do not know how to proceed from here but would be willing to help out. = =20 I apologise to those who may consider this e-mail off-topic, but I just = could not keep silent any longer. Best wishes Tom Nimmo ------=_NextPart_000_0067_01C0A289.E2FB1960 Content-Type: text/html; charset="iso-8859-1" Content-Transfer-Encoding: quoted-printable
Hi all,
 
I am new to this list and have been = learning how to=20 use Cocoon and Tomcat after getting interested in XML.  I have = had=20 real problems with all the documentation. Even Brett McLaughlin's book = "Java and=20 XML", which I bought, seems out of date already - and the = instructions do=20 not work (at least not when I try them).
This means that days, even = weeks are wasted=20 just trying to piece together enough information to get the basic tools = up and=20 running.
I do not mean this as criticism: = preparing=20 documentation is an enormous undertaking, especially doing it  for = people=20 who might have a very "limited" - perhaps non-existent ;) - knowledge, = and=20 particularly when people preparing the documentation are so familiar = with=20 platforms, standards, OSes, programming etc.
 
The point I would like to make is that = we need a=20 new approach to documentation preparation:
 
1 the success of the "works out of the = box"=20 software brigade is precisely because it installs when double-clicked!! = it may=20 not do much else, it will almost certainly adhere to proprietary = standards, but=20 after the excruciatingly painful time I have had to get Cocoon and = Tomcat=20 working, just on a laptop, it is obvious why people stick with "out of = the box"=20 stuff;
 
2 IMHO a new publishing framework will = only truly=20 succeed when non-programmers etc like myself can access the new tools in = a less=20 painful way, gain familiarity with them and think of things to do = with them=20 - this might result in tools being used in ways that are less dominated = by the=20 IT industries various mentalities, and mean that Standards that are set = (by eg=20 W3C) prevail in the longer term;
 
3 the success of open source depends = upon people=20 with limited computer skills being able to specify and use open source = tools in=20 their projects, work etc. without having to run to their sysadmins, = programmers=20 etc every five minutes over what are, to the experienced, ridiculously = simple=20 problems;
 
4 there is also a problem with = accessibility: many=20 people use dial-up to access the internet; in a lot of countries, as = here in the=20 UK, that dial-up is not free of charge - this means that to spend hours = trying=20 to piece together the various, inconsistent sources of documentation, = even the=20 archives, to try and get a picture of how to get something up and = running is so=20 full of frustration and so expensive, that having "played" around = for a=20 while you just retreat and look at the old, proprietary ways of doing=20 things;
 
These problems are not unique to this = project, I=20 have found it before - also with proprietary packages - as I am sure we = all=20 have.  However, just as the internetworked world does not belong = only to=20 the corporates, neither does it belong only to people who are computer = or=20 software experts.  The success of proprietary standards is not = because=20 people are lazy, but because alternative tools are so=20 inaccessible.
 
I would like to help to find a way of = improving the=20 documentation so that the tools are more accessible. 
 
I repeat that this is not a criticism=20 - documentation is a large task and who wants to do that when they = are=20 brilliant software engineers at the cutting edge ;) !! and have so = little=20 time.
 
I do not know how to proceed from here = but would be=20 willing to help out. 
 
I apologise to those who may consider = this e-mail=20 off-topic, but I just could not keep silent any longer.
 
Best wishes
 
Tom Nimmo
 
 
------=_NextPart_000_0067_01C0A289.E2FB1960--