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