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] Commented: (AXIS2-1076) Catchall documentation improvements
Date Mon, 18 Sep 2006 16:03:25 GMT
    [ http://issues.apache.org/jira/browse/AXIS2-1076?page=comments#action_12435508 ] 
            
robert lazarski commented on AXIS2-1076:
----------------------------------------

>From http://marc.theaimsgroup.com/?l=axis-user&m=115859390106189&w=2

Question: Is the userguide example not supposed to be built using the
created ant build file?

Answer: The build file should be used! It works well and is very convenient.

Perhaps a paragraph can be added to the userguide example explicitly stating
that ant (with no parameters) is run from the directory containing
build.xml.


> 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