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: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
