[
https://issues.apache.org/jira/browse/AXIS2-1076?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel
]
Davanum Srinivas resolved AXIS2-1076.
-------------------------------------
Resolution: Won't Fix
> Catchall documentation improvements
> -----------------------------------
>
> Key: AXIS2-1076
> URL: https://issues.apache.org/jira/browse/AXIS2-1076
> Project: Axis 2.0 (Axis2)
> Issue Type: Improvement
> Components: documentation, samples, build,site
> Reporter: robert lazarski
> Assigned To: Chatra Nakkawita
>
> 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.
-
You can reply to this email to add a comment to the issue online.
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
