axis-java-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "M. Goodell" <freebsdu...@yahoo.com>
Subject [Axis2] Learning Axis & Hair Loss
Date Tue, 22 Aug 2006 20:41:36 GMT
 
  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 
Mime
View raw message