Dear Andreas and Marc:

I do not think your QuickStart guide is either accurate or clear. As an example I offer the text on starting the template project (page 28):

- Ensure that the target JBoss is running.
- Start the build with the 'main' target, which can be omitted when it would be the only parameter (it's the default).
- Make sure that the deployment succeeded without any exceptions.
- Start the 'testsuite' build target, but make sure that the template is deployed.
- To start the client, go to the 'build/bin' directory and start the 'run-client' script.
- Use the 'clean' build target to clean up the build and to create the template from scratch (but this does not undeploy the deployed archives).

As a first time user, and also being new to Ant, this kind of writing pretty much stopped me in my tracks. I don't believe you had even explained things like deployment or the testsuite before this. As you know, learning new software is incremental, and not knowing how to execute even a small simple step early on makes it impossible to get to the later steps.

There are also posts to this forum which lead one to believe that aspects of this document are incorrect or out-of-date. You may want to take a look at the forum to get in touch with what people are experiencing.

My own philosophy is that this sort of documentation is no different than software- it either works or it doesn't. If there is a single step that the user cannot go beyond then it does not work and needs to be fixed. Among other things this means you need to test your documentation.

In general, I think open source teams often have a reputation for being more concerned with working on interesting and cool advanced features while looking on newbies to the software as at best a distraction. I believe the JBoss team has tried to avoid this, but unfortunately your "rewards model" (i.e. your developers get paid to write) may not be working, since as far as I can tell they are paid for writing on interesting and cool advanced features but not on the intro documentation. The irony is that your intro documentation will be taken as an indicator of the quality of your advanced documentation- why should I pay for your books if I can't even get through your "Hello World" app? I think there needs to be less emphasis on your moneymakers and more emphasis on helping people get your software up and running. And here's something to keep in mind: a lot of downloads does not necessarily mean a lot of people are using it.

I would like to close by saying that I am posting this message because the only way to communicate with the JBoss team appears to be by posting messages to a forum that they will probably never read. This is a recipe for frustration. I do not think it is right to put a flawed document out there and then make yourselves unavailable; I think you need to take responsibility for your product. That is what all good companies do.

Thank You

Dean McQuiston