Editorial comments on the Primer

Hi,

Below are my editorial comments for the Primer. I am working on my  
set of semantic comments for the Primer which I hope to provide by  
mext weeks call at latest.

Cheers,

-Charlton.

Charlton Barreto
P 1.408.536.4496
cbarreto@adobe.com
www.adobe.com


Primer Editorial Comments
Section 1.1, Paragraph 1, Sentence 2
I would suggest rewording this into something similar to: "The first  
three sections are intended for both audiences, while the last is  
intended primarily for software professionals."

Section 1.1, Paragraph 1, Sentences 3 & 4
I would suggest inverting these two sentences, and simplifying into  
something similar to: "The first half of section 3 describes and  
example using UML diagrams; the second half walks through building a  
WS_CDL description of the example."

Section 1.1, Paragraph 1, Sentence 5
I would suggest inverting the phrases in this sentence and reworking  
into something similar to: "The former is targeted at both audiences  
of this document, while the latter is primarily directed at software  
professionals, yet can be useful to business analysts for further  
context and understanding."

Section 2, Paragraph 2, Sentence 2
This sentence may read better as: “The distinction between SOA and  
Web services is that the latter requires a Web Services Description  
Language (WSDL) interfaces, while the former may not have one.”

Section 2, Paragraph 2, Sentence 3
Change "Web Service Services" to "Web Services"

Section 2, Paragraph 3, Sentence 6
Suggest we revise this to read: "What WS-CDL allows one to do is  
describe the effective ordering constraints across the services and  
so describe the common rules and common behavior in order for the  
services to collaborate, which is why we call it “common  
collaborative behavior”."

Section 2, Paragraph 4, Sentence 2
Suggest we revise this to read: "Instead, it describes as peers the  
entire collaborative observable behavior of all of the services, such  
that no one service can be said to exert control over any other  
service. In effect, it describes the services as a complete  
distributed application, in which each service plays a distinct role,  
and has distinct relationships with it’s peer services."

Section 2, Paragraph 5, Sentence 2
Suggest we revise this to read: "The least interesting scenario,  
which WS-CDL can be used to describe, is a set of services that never  
synchronize at all; that is, there are neither any observable  
relationships and or any statement of an unobservable relationship  
between the services."

Section 2, Paragraph 5, Sentence 3
Suggest we revise to read: "In this case, the services perform a  
choreography, but effectively on different stages, and thus need no  
form of coordination (e.g. a buyer and seller choreography for  
WalMart versus a Bloomberg Reuters choreography for the exchange of  
news items). In all other cases, the synchronization is what makes  
the interaction interesting (e.g. a buyer-seller choreography coupled  
with a seller credit check choreography or indeed a seller shipper  
choreography)."

Section 2, Paragraph 6, Sentence 1
Suggest we revise the last part of this sentence to read: "(e.g. has  
the bartering choreography between buyer and seller “started”, or has  
it “finished”)."

Section 2.1, Paragraph 1
Suggest we revise this to read: "WS-CDL is a description language,  
not an executable language - hence the term “Description” in it’s  
name. As it is a language that can be used to unambiguously describe  
observable service collaborations, we might also refer to this as  
business protocols within and across domains of control, that govern  
how the services interact."

Section 2.1, Paragraph 2, Sentence 1
Suggest we revise this to read: "When WS-CDL is focused on describing  
collaboration within a domain of control, it is used to describe the  
internal workflows that involve multiple services (also called end- 
points) that constitute observable collaborative behavior."

Section 2.1, Paragraph 2, Sentence 2
Would it be preferable to use "negotiated" rather than "agreed" in  
this sentence?

Section 2.1, Paragraph 2, Sentence 4
Suggest we revise this to read: "You can think of it as a way of  
ensuring services are well-behaved with respect to the goals you wish  
to achieve within your domain."

Section 2.1, Paragraph 3, Sentence 1
Suggest we revise this to read: "When the focus is across domains of  
control, WS-CDL is used to describe the business protocols that exist  
across domains...."

Section 2.1, Paragraph 3, Sentence 2
Suggest we revise this to read: "These protocols have some form of  
XML data format definition and proceed to describe the ordering of  
message exchanges using a combination of prose and UML sequence  
diagrams."

Section 2.1, Paragraph 3, Sentence 3
Suggest we revise this to read: "WS-CDL provides  an unambiguous way  
of describing the ordering of message exchanges, and in so doing,  
ensuring that the services that participate in observable  
collaborations based on such vertical standards can be guaranteed to  
conform to the choreography description."

Section 2.1, Paragraph 3, Sentence 4
Suggest we revise this to read: "You can think of it as a way to  
ensure that services are well-behaved with respect to their common  
goals across domains."

Section 2.2, Paragraph 2
Suggest we revise the last part of the paragraph to read:  
"...services that participate in a choreography are well-behaved on a  
continuous basis."

Section 2.2, Paragraph 3
Suggest we revise this to read: "Both these benefits translate into  
greater up-time, and so increase top line profits. At the same time,  
they translate into less testing time and so reduce cost of delivery  
which decreases bottom line costs."

Section 2.3, Paragraph 1, Sentence 1
Suggest we revise this to read: "WS-CDL is a layered language that  
provides different levels of expressability to describe a choreography."

Section 2.3, Paragraph 1, Sentence 2
Would it be preferable to use "illustrated" rather than "shown"?

Section 2.3, Paragraph 5, Sentence 1
It would be preferable to replace "because" with "as".

Section 2.3, Paragraph 5, Sentence 2
Suggest we revise this to read: "...rather, they observe visible  
interactions and use the observations to determine their state with  
respect to the other roles."

Section 2.3, Paragraph 6, Sentence 1
Suggest we revise this to read: "Some business protocols are defined  
exposing specific business rules."

Section 2.3, Paragraph 6, Sentence 2
Suggest we revise this to read: "These constitute shared knowledge  
between the concerned roles; for example, we may terminate an order  
completion between a buyer and a seller when we calculate that the  
items delivered match the original order."

Section 2.3, Paragraph 6, Sentence 4
Suggest we revise this to read: "...which implies that state  
management is needed."

Section 2.3, Paragraph 7, Sentence 1
Suggest we revise this to read: "...globally accessed  – or at least  
accessed between roles - when needed."

Section 3, Paragraph 1, Sentence 2
Replace "and" with "an". Remove extraneous "e".

Section 3.1, Paragraph 1, Sentence 2
Remove "In this example" so that the sentence reads: "The buyer  
interacts with the seller...."

Section 3.1, Paragraph 1, Sentence 3
Suggest rewording to: "When a price is acceptable to the buyer, the  
buyer orders the relevant goods based on it, whereupon the seller  
checks their credit worthiness."

Section 3.1, Paragraph 1, Sentence 4
Suggest rewording to: "If this is acceptable, the seller requests a  
delivery date from the shipper."

Section 3.1, Paragraph 1, Sentence 5
Suggest rewording to: "In the example, the shipper communicates  
directly with the buyer once an agreed delivery date has been  
achieved, and informs the buyer of the delivery details."

Section 3.1, Paragraph 3, Sentence 1
Suggest rewording to: "The Normal Collaboration, illustrated in  
Figure 2, shows the buyer requesting a quote and the seller  
responding with a quote."

Section 3.1, Paragraph 3, Sentence 3
Suggest rewording to: "As the buyer’s credit rating is acceptable,  
the seller then confirms the order with the buyer and requests from  
the shipper delivery details that are passed back to the seller by  
the shipper."

Section 3.1, Paragraph 4, Sentence 4
Suggest rewording to: "The shipper will have picked up all that is  
necessary from the seller, which received it from the buyer...."

Section 3.1, Paragraph 5, Sentence 1
Would it be preferable to use "illustrated" rather than "shown"?
Also reword the last phrase to read: "...and the seller sending back  
a quote response with an associated timeout."

Section 3.1, Paragraph 5, Sentence 2
Suggest rewording the last phrase to read: "...demonstrating a  
classic race condition between the parties."

Section 3.1, Paragraph 6, Sentence 1
Would it be preferable to use "illustrated" rather than "shown"?

Section 3.1, Paragraph 6, Sentence 2
Suggest rewording to read: "After the buyer requests the quote, the  
seller responds, the buyer accepts it, the seller then checks the  
credit rating for the buyer."

Section 3.1, Paragraph 6, Sentence 3
Suggest rewording to read: "In this case, the credit check agency  
determines that the credit rating is low, and returns a credit  
rejection to the seller, who in turn sends a credit rejection to the  
buyer and terminates the collaboration."

Section 3.1, Paragraph 7, Sentence 1
Would it be preferable to use "illustrated" rather than "shown"?

Section 3.1, Paragraph 8, Sentence 3
Suggest rewording to read: "The seller may respond by accepting the  
quote, sending a quote response message back to the buyer."

Section 3.1, Paragraph 8, Sentence 4
Suggest rewording to read: "If the seller does not respond, the  
buyers update is subject to a timeout in the same way as the sellers  
quote is valid for a specified duration."

Section 3.1, Paragraph 8, Sentence 5
Suggest rewording to read: "In receipt of a quote response from the  
seller, the buyer may accept the quote (by so doing enter into the  
act of buying with the seller), may request a further updated quote,  
or simply do nothing at all – allowing the quote to timeout."

Section 3.2, Paragraph 1, Sentence 1
Suggest rewording to read: "In this section we introduce the  
fundamental concept of an interaction, which underpins WS-CDL thus  
defining the roles, tokens, channels, relationships, participants and  
variables necessary to use an interaction in describing the example’s  
business protocol."

Section 3.2.1, Paragraph 1, Sentence 1
Suggest rewording to read: "The difference between roles and  
participants will be detailed later on; for the time beingwe can  
consider them as synonymous."

Section 3.2.1, Paragraph 2, Sentence 1:
Suggest rewording to read: "A collaboration is message exchange  
between the swim lanes of a sequence diagram."

Section 3.2.1, Paragraph 4, Sentence 1:
Suggest rewording to read: "In the example, when the buyer accepts a  
quote, it does some extra things so that the seller, on behalf of the  
buyer, can pass certain contact details to a third party. This third  
party can then contact the buyer to inform the buyer of the delivery  
details."

Section 3.2.1, Paragraph 4, Sentence 2:
Suggest rewording to read: "The buyer sends a quote acceptance to the  
seller. "

Section 3.2.1, Paragraph 4, Sentence 4:
Suggest rewording to read: "The shipper then uses this additional  
information to directly respond to the buyer."

Section 3.2.1, Paragraph 6, Sentence 1:
Suggest rewording to read: "In order to describe our interactions, we  
shall have to define the channelTypes for the channelVariable in the  
interaction, and for the channelTypes that enable channels to be  
passed between roles."

Section 3.2.1, Paragraph 12, Sentence 2:
Suggest rewording to read: "This simply allows the interaction to be  
referenced."

Section 3.2.1, Paragraph 12, Sentence 3:
This sentence may not be necessary. If retained, though, I would  
suggest rewording it to read: "We have chosen a long name for the  
sake of illustration, but in practice, shorter program-code based  
names would be more likely."

Section 3.2.1, Paragraph 14, Sentence 1:
Suggest rewording to read: "At this point, we can start to see that  
channels are an important part of the structure of a choreography."

Section 3.2.1, Paragraph 14, Sentence 3:
Suggest rewording to read: "We can also see the importance of the  
operations in how they are defined and bound to the choreography."

Section 3.2.1, Paragraph 16:
Suggest rewording to read: "In our example, we can go further as the  
exchange element also describes the variable in which an instance of  
a "2BuyerChannelType" is held at the buyer -  namely, the  
'DeliveryDetailsC' variable - and where its exchange will be rendered  
– in this case, into a variable of the same type called  
'DeliveryDetailsC'  that resides at the seller. In the send variable  
and receive variable, the variables are accessed using a WS-CDL  
function which names the variable, and optionally the role at which  
the variable resides. It this case, the latter parameter is not used,  
and is inferred based on the context. The context itself is based on  
the two ends of the channel and direction of the interaction."

Section 3.2.2, Paragraph 2, Sentence 2:
Suggest rewording to read: "This is the core of collaboration -  
identifying common interaction between peers."

Section 3.2.2, Paragraph 4, Sentence 2:
Suggest rewording to read: "This solely provides a name for the type  
of role we are defining. In the case of the buyer,  we name it  
"BuyerRoleType"; then the "BuyerBehavior" is a name used to bind the  
implementation of an "BuyerRoleType" at some service end point."

Section 3.2.2, Paragraph 1, Sentence 3:
Suggest removing "So" such that the sentence reads: "In our example...."

Section 3.2.2, Paragraph 3, Sentence 2:
Replace "althought" with "though".

Section 3.2.6, Paragraph 8, Sentence 2:
Suggest rewording to read: "Firstly, the buyer sends a message to the  
seller accepting the quote, then sends a further message to the  
seller with the details of a channel that it passes to the seller."

Section 3.2.6, Paragraph 8, Sentence 4:
Suggest rewording to read: "This is done so that the buyer can  
receive delivery details back from a third party of which it has no  
knowledge."

Section 3.2.6, Paragraph 8, Sentence 5:
Suggest rewording to read: "This is achieved through channel passing,  
where we add details to a channel allowing it to pass others of a  
particular type."

Section 3.3, Paragraph 1, Sentence 1:
Suggest rewording to read: "...we can now begin to consider  
describing the choreography itself."

Section 3.3.1, Paragraph 2, Sentence 2:
Suggest replacing "And we shall..." with "We shall also...."

Section 3.3.1, Paragraph 5, Sentence 2:
Suggest replacing "And variables have..." with "Variables also have...."

Section 3.3.1, Paragraph 5, Sentence 7:
Suggest rewording to read: "...in some way, which can only be done...."

Section 3.3.1, Paragraph 6, Sentence 1:
Remove the superfluous "the" ("The abstract syntax for a  
choreography....").

Section 3.3.3, Paragraph 2, Sentence 2:
Would it be preferable to use "illustrated" rather than "shown"?

Section 3.3.3, Paragraph 3, Sentence 3:
Suggest rewording "If it is false..." to "If false...", rewording the  
last phrase to read "as the condition ("barteringDone") itself  
evaluated to true", and removing the following sentence (Sentence 4).

Section 3.3.4, Paragraph 4, Sentence 1:
Suggest rewording to read: "The body of the above workunit is a  
choice. "

Section 3.3.5, Paragraph 2, Sentence 5:
Replace "effect" with "affect".

Section 3.3.6, Paragraph 1, Sentence 3:
Replace "detail" with "details".

Section 3.3.6, Paragraph 2, Sentence 3:
Replace "effect" with "affect".

Section 4.1, Paragraph 1, Sentence 4:
Reword to read: "...and make it a blocking workunit."

Section 4.1, Paragraph 3, Sentence 3:
Reword to read: "...which means that the two workunits operate  
concurrently. "

Section 4.1, Paragraph 3, Sentence 4:
Reword to read: "Obviously the second, being dependent on the first,  
waits until it’s preconditions are met before proceeding."

Section 4.1, Paragraph 4, Sentence 1:
Reword to read: "...how we handle the credit checking response, by  
introducing another variable, 'creditRatingOk', at the seller role,  
that records, as a Boolean, the response from the credit check. "