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
Nicholas Gallardo
<nickgalla...@yah
oo.com> To
[email protected]
09/10/2009 02:53 cc
PM
Subject
Re: Apache Wink Devloper Guide
Please respond to Documentation
wink-...@incubato
r.apache.org
> 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
