Hi Wendy, First of all thanks for all the feedback, I have already implemented the link suggestion that you made for section 2 (Chapter 2) of the developer guide. I will also eventually incorporate a summary into each section.
Section 2 is designed as an introductory section or preamble to the rest of the guide designed for those of amongst us who don't need to read the whole thing to get the picture, that is why the information seems to reiterate itself, I have added another sentence to the introduction of the section in order to clarify this issue that you raised. As far as the other section (chapters) are concerned, I have only just begun to write the guide, thus there are still many inconsistencies throughout the guide, that is why I only asked for a review on the first two sections. In any case thanks for the tips. I will try to respond to all the issues that you raised asap. Thanks, Michael From: Wendy C Raschke [mailto:[email protected]] Sent: Thursday, September 10, 2009 11:58 PM To: [email protected] Subject: Re: Apache Wink Devloper Guide Documentation Disclaimer: Remember I am new to Wink and JAX-RS, and have large gaps of understanding, so take these suggestions with that grain of salt. :) * Chapter 2, "Apache Wink Building Blocks" is divided into three subsections: "Service Implementation Building Blocks", "Client Components Building Blocks", and "The Apache Wink Runtime." It appears that the guide then has comparable, whole chapters detailing further the client (chapter 6: "Apache Wink Client") and the Wink runtime (chapter 5: "Apache Wink Server"). Would you consider creating a whole chapter devoted to the service implementation component of Wink? I looked for a chapter about Resources and all the related concepts (such as what is described in chapter 3 of the JAX-RS specifiction) and was thrown off when I didn't find one in the TOC. If such a chapter is not deemed necessary because of the detail already included in the overview, could you consider moving that detail into an entirely separate chapter? * At the top of chapter 2, can you make each of the bulleted items a link? It would make this long article more navigable. Or perhaps the three subsections can be compartmentalized into their own pages (such as what is done with the "Apache Wink Server Module" chapter). * At the end of "subsection 1," there is a heading titled "Apache Wink Building Blocks Summary." But the other subsections don't have this sort of summary. Could this inconsistency confuse customers? * The "Service Implementation Building Block Overview" subsection references the Bookmarks example to illustrate some points, but the client subsection doesn't use any examples. I'm not sure, but it doesn't look like the Bookmarks example contains a client--is this true? I know you are just asking for feedback on section 1 and 2, but I went ahead and looked at chapter 6 ("Apache Wink Client") and didn't see that it referenced any of the examples included with Wink, like GoogleDocs-client or QADefects-client. Since other documentation references an example included with the product, could we also reference the bundled example clients as well? * I'm confused by the mention of "Assets," which are "classes that contain "web service business logic" implemented by the developer. Each Asset is associated with one or more URI." I'm not sure how an Asset is different from a Resource, which the text says also implements business logic and that "a resource is bound or anchored to a URI space." The two concepts seem to be very similar to each other. I searched for "Asset" in the JAX-RS specification and didn't find any mention of it. I'm sure my confusion is largely due to my relative unfamiliarity with JAX-RS and Wink, but perhaps a clarification on the difference might be helpful. * And on a more general topic, can you consider creating a section that highlights how JAX-RS differs from JAX-RPC, JAX-WS, and other web services for J2EE? For example, identify that the messages aren't wrapped in SOAP, how there are no WSDL files to describe the contract between client and server, or how JAX-RS is very HTTP-centric--all the major characteristics that set it apart from the other programming models? I say this because I imagine lots of customers will have come from backgrounds where they used JAX-RPC, JAX-WS, or SAAJ, and are accustomed to the JSR-109 paradigm of web services. I know the differences of JAX-RS totally threw me off. Thank you, Wendy >^. .^< ~ -- Ciao and Meow [cid:[email protected]]Nicholas Gallardo <[email protected]> Nicholas Gallardo <[email protected]> 09/10/2009 02:53 PM Please respond to [email protected] To [email protected] cc Subject Re: Apache Wink Devloper Guide Documentation > Do you want my feedback here, sent to this list, or sent privately to you > alone, or...in some other forum? I would suggest that it go either to the list or via JIRAs. Either way, it should be openly available. -Nick ________________________________ From: Wendy C Raschke <[email protected]> To: [email protected] Sent: Thursday, September 10, 2009 2:46:38 PM Subject: Re: Apache Wink Devloper Guide Documentation Hi, Michael, I'm new to Wink. I work on customer problems found in the JAX-RPC and JAX-WS runtimes of WebSphere (an IBM product--sorry if I'm being so obvious but I don't want to assume). I'm very happy to review your developer guide--I'm finding it very insightful and helpful in getting up to speed. My goal is like everyone else's on this list: to help make Wink as user-friendly and understandable to customers as possible. I imagine the documentation is the first exposure customers have with the product, as it is with me. Do you want my feedback here, sent to this list, or sent privately to you alone, or...in some other forum? Thank you, Wendy >^. .^< ~ -- Ciao and Meow "Bruggeman, Michael" <[email protected]> "Bruggeman, Michael" <[email protected]> 09/10/2009 06:06 AM Please respond to [email protected] To "[email protected]" <[email protected]> cc Subject Apache Wink Devloper Guide Documentation Hi All, I would like to draw your attention to the "Apache Wink Wiki" site, there I have created the documentation for the Apache Wink project. The documentation, titled "Apache Wink Developer Guide" contains the latest information pertaining to the current version of Apache Wink. In order to improve and streamline the documentation process I would please ask that the following guidelines are adhered to: When adding a new topic to the TOC (or anywhere in the documentation) make sure to add underneath the heading "TDB" (to be defined), also write your name there so that I will be able to track the progress on the new topic and also review the content as well as have the name of the person who is responsible for adding the content to the Wiki. Please Note: adding your name is very important because it will enable me or anyone else to refer to the correct person, saving time. Also, please review the documentation, adding relevant points where necessary. I have finished writing the first two section of the Wiki, titled: Introduction to Apache Wink and Apache Wink Building Blocks. Please review these two chapters (sections) and send me your feedback, as I complete additional chapters (sections) I will send an e-mail notification asking for review and feedback. Your input is valuable to me, please add topics and review the wiki content. Thanks, Michael Bruggeman
