cocoon-users mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "tom" <...@tnimmo.co.uk>
Subject documentation
Date Thu, 01 Mar 2001 19:57:38 GMT
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. 

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.  

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

Mime
View raw message