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.
I would gladly help them debug/review it and give
feedback if I just could get hold of the correct template project. It would make things much easier.
Don't you all agree?
> 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?
Absolutely. I have money to buy the doc from jboss.org. No problem. I am however afraid about their quality given the incomprehensible mumbling of "Getting Started"...
The goal of free documentation should be to let me have a simple project. Then, when I am convinced jboss is enough for my needs (I am sure it is) and I want to know something more about "how" it works, I would buy the advanced docs or directly donate something to Jboss.org...
Agreed, I just got through the Getting Started 3.0 Doc, it needs a lot of work, no question....
Lots of broken sentences, incomplete examples, etc...
How does it compare to the advanced docs?
I agree the Getting Started doc is rough, but you get what you paid for. It needs to be updated and provide more of a tutorial/hello-world, perhaps be written by a professional technical writer.
For $10, you can get the Administration and Development documentation. You get a lot less handholding and more info about the inner-workings of JBoss. It's great if you've work with app servers before and a really good understanding of enterprise Java.
Once I got my server running (using a copy of the default server), I haven't really had to use the documentation or mess with the configurations. I'm not trying any advanced configurations. I've spent more time working with Ant, Xdoclet and MySQL to get an EJB deployed and talking to the database.
How is you lack of ant skills reflecting on JBoss documentation?
Its not 1996..with using make clearly you need to leran ant and do some projects before going through JBoss user docs..
If you look in the beginning fo most current Java User docs of complex systems the first warning is telling you need knowledge and skill in using ant amoung other issues..
Jboss docs cannot teach how to use ant or how to program in java as they are not designed for that function...
Please notice that JBoss is often quickly evaluated as alternative for BEA/IBM on smaller projects by large consultancies/integrators. There's no time for 'fixing'. Quick judgement is 'probably superb; not ready for business as of today'.
Lost half a day, you lost potential client(s), Messieurs.
W. Bek, London
On Wall Street, it's still 1986 in most places. Only with great trepidation do we make progress. Managers are more concerned with the value of their options than the quality of their systems.