axis-java-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "robert lazarski (JIRA)" <j...@apache.org>
Subject [jira] Created: (AXIS2-1076) Catchall documentation improvements
Date Fri, 25 Aug 2006 13:07:22 GMT
Catchall documentation improvements
-----------------------------------

                 Key: AXIS2-1076
                 URL: http://issues.apache.org/jira/browse/AXIS2-1076
             Project: Apache Axis 2.0 (Axis2)
          Issue Type: Improvement
          Components: samples, build,site  & docs
            Reporter: robert lazarski


I'm going to include some constructive critisism from M. Goodell here and hopefully we can
get some more comments on what we can improve, with the intent being to improve the docs for
the 1.1 release . 

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.
 

-- 
This message is automatically generated by JIRA.
-
If you think it was sent incorrectly contact one of the administrators: http://issues.apache.org/jira/secure/Administrators.jspa
-
For more information on JIRA, see: http://www.atlassian.com/software/jira

        

---------------------------------------------------------------------
To unsubscribe, e-mail: axis-dev-unsubscribe@ws.apache.org
For additional commands, e-mail: axis-dev-help@ws.apache.org


Mime
View raw message