[ http://issues.apache.org/jira/browse/AXIS2-1076?page=all ]
Davanum Srinivas updated AXIS2-1076:
------------------------------------
Component/s: documentation
> 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, documentation
> 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]
