[ http://issues.apache.org/jira/browse/AXIS2-1076?page=comments#action_12430578 ] Derek Foster commented on AXIS2-1076: -------------------------------------
First of all, I'd like to mention AXIS2-917 here, which notes that the user guide needs to describe faults and fault handling. Secondly, some questions that I've noticed perpetually get re-asked on the mailing list include: How do I report a bug? (This should describe the fact that you can't enter bugs against AXIS2 without first registering on the JIRA site). Also, it should describe including WSDL and/or XSDs under appropriate circumstances. What is document-wrapped mode? What will trigger its invocation in Axis? (Anne Thomas Manes has a good webpage on this. It might be nice to get a simplified version put directly into the user guide, if she is agreeable) What *exactly* does someone need to download and execute in order to successfully build a development environment? (Which version of Maven, etc.) How to handle cases in which a service must be invoked which takes no parameters. How to handle cases in which a service must be invoked which returns no parameters. How to run Axis without an application server (using SimpleAxisServer). How to access the SOAP header? How a user service can provide a method to allow Axis2 to pass a message context to it (Including implementing the interface defined for the purpose). The difference between RPC/encoded mode and document/literal, how to tell which is being used in a WSDL document, and why one is supported in Axis2 and the other is not. What is HTTP chunking, how do I recognize it, and how do I turn it on/off? (Personally, I think it should be off by default...this seems to cause a lot of confusion) The inability of Axis to tell the difference between operations which have the same operation signature (even if they have different operation names), and how SOAPAction does/does not relate to this. The fact that some of the Eclipse tools currently don't work properly when using Axis. (I don't use Eclipse, so I don't know which ones, but people seem to discuss this frequently on the mailing list, and are perpetually surprised to discover this fact.) An explanation of what the WS-I Basic Profile is, and a pointer to some tools that can be used to automatically detect if a specific WSDL document is valid or not according to the WS-I basic profile. A pointer to an *ACCURATE* and *UP TO DATE* list of valid command-line options for WSDL2Java and Java2WSDL. (note that there have been various changes since the current version was produced. For instance, you can now list multiple namespace2Package lines, and namespace2Package can take a single parameter which is a filename containing mappings. There are probably other discrepancies. References to the other documents referenced on the Axis2 website which are still up-to-date and which cover particular topics well. (There are a lot of documents and external websites referenced on the site, and it is often impossible to tell which ones someone should read without actually opening and reading each one. Also, when reading one, it is often not possible to tell if the document is describing obsolete features or is describing features in Axis that don't exist in Axis2). Personally, I'd like to see an actively maintained Frequently Asked Questions list on the Wiki website, editable by anybody who is willing to register, with people actively directed to read that page before asking questions on the mailing lists. That way, whenever a common question gets asked and correctly answered on the mailing list, we can add it to the FAQ and hopefully reduce the traffic on the lists a bit. > 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]
