cocoon-users mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Tapan Nanawati" <tapan_nanaw...@yahoo.com>
Subject RE: documentation
Date Thu, 01 Mar 2001 21:39:09 GMT
Tom
Sorry but I disagree with you. My experience for installation has been a
good one. If the cocoon installation instructions are obeyed to the point -
It will install with "double -click" as you want it to (and a few
instructions). It wont install only if accidently a small point is misssed.
If there is an installation documentaion available it is really sure to
install. If there is no documentation, then ofcourse someone has to take
soem pains. Everyday some one is installing on a new platform and sharing
their thoughts over here. And it gets included in the new release. We all
help out here for new platform installations.
But your thought of contributing is a great idea. Cheers for that.
Tapan Nanawati
tapan_nanawati@yahoo.com
91-11-6685274 (o)
91-98112-98982 (m)
New Delhi - INDIA
------------------------------
God is real, unless declared integer.

  -----Original Message-----
  From: tom [mailto:tom@tnimmo.co.uk]
  Sent: Friday, March 02, 2001 1:28 AM
  To: cocoon-users@xml.apache.org
  Subject: documentation


  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