Here's a tutorial on AXIOM: http://ws.apache.org/axis2/1_0/OMTutorial.html
(The developers are busy fixing bugs -- unfortunately, the
documentation will come later. But please continue to provide
constructive criticism. Perhaps you could compile a list of things you
found unintelligible and create a JIRA requesting they by improved.)
Anne
On 8/22/06, M. Goodell <[EMAIL PROTECTED]> wrote:
First of all let me preface what I am about to say by stating clearly:
I really appreciate the work that goes into open source projects like Axis.
I know this is a "labor of love" in many respects and people choose to do
this with no direct monetary compensation whatsoever. To all of you
dedicated passionate developers on Axis2 & other open source projects I'm
sure I speak for thousands when I say Thank You!!
With that said, over the past years as I have worked with various open
source projects and have found one common problem with most of them:
The problem: Documentation and reference material.
I have found Axis2 be the same way. Please allow a couple of examples:
1. In the users guide that demonstrates how to build a web service using the
Axis2s primary APIs there is the sample code
public void ping(OMElement element){} //IN-ONLY operation, just accepts the
OMElement and do some processing.
public OMElement echo(OMElement element){}//IN-OUT operation, accepts an
OMElement and // sends back the same again
The questions that popped up in my mind after reading this were:
1. What's an OMElement?
2. What's an IN-ONLY operation?
3. What's an IN-OUT operation?
etc . . .
Then below the code example is this statement:
"As you can see, the two operations are very simple and need no explanations
on what they do"
Yes, the operations in and of themselves are not complex at all but there is
some very foundational information missing here. i.e. items 1,2 & 3
It seems, to me anyway, much of the documentation assumes familiarity with
concepts and technologies used. In this case AXIOM.
2. The services.xml file example as demonstrated in the users guide is
another item I would like to point out. I have looked for the reference to
what each element is such as a DTD description etc. But no such luck. Very
frustrating! Where does one go to get this information??
Much of the documentation is assembled in this fashion. Moreover, I have
seen posts in the newsgroups about the Axis documentation being difficult to
follow and find information.
In summary, what I, and perhaps others, are asking for is a more clearly
defined, logical, orderly & complete path to learning, in this case AXIS2. I
am not afraid to read anything, I just need to know what and when. I believe
good technical documentation should supply that opportunity and road map.
Am I asking something from the open source community that simply does not,
and never will exist?
Will I need to await a text book on subject *hoping* it' not just a rehash
of material already on the web?
Do we need to spend the money on a commercial application and forget open
source? The documentation is in many cases better, hence a faster ascent up
the learning curve.
Finally, does anyone else share my frustration or do I simply need to end my
20+ career as a programmer and go work in a pet grooming shop for the rest
of my days?
(Don't answer that!)
It just seems a shame and waste to see such useful technology not used
perhaps due in large part to proper explanation and systematic exposure on
the part of those responsible for bringing it to the marketplace.
I welcome and invite others thoughts and opinions on this topic.
Respectfully,
M Goodell
________________________________
Get your email and more, right on the new Yahoo.com
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
