Dear Andreas, Marc, et al:

Is there any way the source code for the Getting Started documentation can be put into the jboss project itself? There are many, many, MANY problems that I'm seeing and running into -- and the draft4 documentation is woefully incomplete and inadequate to the task. (Among other things, there should be a easily- and centrally-referenced pointers to where to download various things, such as ant, XDoclets, and the template project; there should be no reference to port 8082; there should be much less of the 'preaching' tone that it takes [I didn't download it and try to use it to be preached at why it makes so much more sense to use JBoss than anything else, and I resent that tone being taken with me], and many more step-by-step examples without anywhere near as much topic wandering/drift.)

Yes, you're writing documentation for developers. However, the style that works best for a tutorial is not the style that works for marketing, which is not the style that works best for reference, which is not the style that works best for conveying large amounts of information -- and it takes a programmer with technical writing experience to be able to clearly and concisely explain what is most important, as well as allude to the complete picture.

As I am a programmer with technical writing experience, I'd like to be able to contribute documentation patches to the Getting Started guide. Since this is my first exposure to the world of J2EE, to the world of JBoss, and to getting my applications to run under a standardized environment, I have a unique perspective -- the ability to point out where the documentation falls woefully short, and the things that it doesn't teach that need to be taught for a basic ground-level understanding of how to use JBoss. (Isn't that what the Getting Started documentation is for?)

(Furthermore, there's one area of documentation that I haven't seen, yet: the guide not for the developer, but for the administrator who has to get it and keep it all up and running. I don't know about you, but a gentle, 10-to-30 minute read explaining what a .war file is, what a .sar file is, what 'deployment' is and how to do it, how to set properties for packages before and after deployment, how to deploy to the root of the server, how to set up additional ports for web services with their own application spaces, how to read the logging that the server spits out, and how to troubleshoot errors... basically, the things that an administrator needs to know to be able to configure the environment to suit his/her own needs, and keep it running.)

I hope you take these suggestions in the spirit in which they are intended. I'm quite certain that JBoss is a wonderful tool... but without knowing how to use a tool, a tool is meaningless. Without the Getting Started documentation being up to snuff, there's no way that people who can't get the server working are going to buy the advanced documentation, nor indeed spend any more time getting the server to work -- which will lead, inevitably, to a solidly entrenched camp of people who have no patience for JBoss, and will recommend or authorize the purchase of other products in its place.

Sincerely,

Kyle Hamilton