Let me add bit more to what Anne has said. First I really appreciate your comments on this.
All the documentation we have in Axis2 and AXIOM were written by the developers of the respective projects. We always didn't have enough time to improve the docs, which I know is not a good excuse. We tried to explain as much as possible from developer pov, but I admit that it is not that successful. Couple of guy have now started writing some articles to various places on the web. I'd happy to get feedback like this and appreciate if someone can help us to improve the docs. Even though we have written some good piece of code, its you people that are using it. So can you people help us to improve the docs and we will give any support from technical content. Robert is another guy who had all sorts of troubles in understanding how it works and he has a better knowledge. Perhaps he might help too with docs. If anyone of you have time to help the community writing docs, please go ahead, write them, create a JIRA and attach them. If you have questions, feel free to ask them either in axis-dev and/or axis-user lists. Thanks, Chinthaka Anne Thomas Manes wrote: > Here's a tutorial on AXIOM: http://ws.apache.org/axis2/1_0/OMTutorial.html > > (The developers are busy fixing bugs -- unfortunately, the > documentation will come later. But please continue to provide > constructive criticism. Perhaps you could compile a list of things you > found unintelligible and create a JIRA requesting they by improved.) > > Anne > > On 8/22/06, M. Goodell <[EMAIL PROTECTED]> wrote: >> >> >> First of all let me preface what I am about to say by stating clearly: >> >> I really appreciate the work that goes into open source projects like >> Axis. >> I know this is a "labor of love" in many respects and people choose to do >> this with no direct monetary compensation whatsoever. To all of you >> dedicated passionate developers on Axis2 & other open source projects I'm >> sure I speak for thousands when I say Thank You!! >> >> With that said, over the past years as I have worked with various open >> source projects and have found one common problem with most of them: >> >> The problem: Documentation and reference material. >> >> I have found Axis2 be the same way. Please allow a couple of examples: >> >> 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. >> >> Am I asking something from the open source community that simply does >> not, >> and never will exist? >> >> Will I need to await a text book on subject *hoping* it' not just a >> rehash >> of material already on the web? >> >> Do we need to spend the money on a commercial application and forget open >> source? The documentation is in many cases better, hence a faster >> ascent up >> the learning curve. >> >> Finally, does anyone else share my frustration or do I simply need to >> end my >> 20+ career as a programmer and go work in a pet grooming shop for the >> rest >> of my days? >> >> (Don't answer that!) >> >> It just seems a shame and waste to see such useful technology not used >> perhaps due in large part to proper explanation and systematic >> exposure on >> the part of those responsible for bringing it to the marketplace. >> >> I welcome and invite others thoughts and opinions on this topic. >> >> Respectfully, >> >> >> M Goodell >> >> >> ________________________________ >> Get your email and more, right on the new Yahoo.com >> >> > > --------------------------------------------------------------------- > To unsubscribe, e-mail: [EMAIL PROTECTED] > For additional commands, e-mail: [EMAIL PROTECTED] > >
signature.asc
Description: OpenPGP digital signature
