Thanks for doing the updates. One minor nitpick, I think all the acronyms (REST, HTTP, URI, URL, MIME, JSON, etc.) should be capitalized. I tried capitalizing all the ones I could find. I like the links at the top to make chapter 2 easier to click through.
For the Chapter 2, Building Blocks, I think we should drop the internal Deployment Configuration section from that page, and then add a blurb about the public HandlersFactory with more info over at the Handlers chains. One organizational change I would like to make is to add a Chapter 1.5 Quick Start Guide. Something small like http://cwiki.apache.org/confluence/display/WINK/JAX-RS+Getting+Started for the Server side and another one for the client. It may be just me but after Chapter 2, I'm exhausted, and I'm thinking "if I have to read all this stuff before I even write a line of code for a supposedly easy and simple REST service, I give up". IMO, as someone wanting to pick up new technology/features, I always like to see a "one page" example that shows enough to get something running without having to read lots of text. Anyway, just my thoughts. Maybe easier to add two new sections to Chapter 1. Please let me know if this is something worth adding. On Mon, Sep 14, 2009 at 6:37 AM, Bruggeman, Michael <[email protected]> wrote: > 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 > > > > -- - Bryant Luk
