documentation

[tom <to...@tnimmo.co.uk>]

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