w3c ws cdl 2/14/2006: More comments on WS-CDL Primer Sections 1-3

Continue comments for Sections 1-3 (now complete). Overall these 
sections flow OK.

General:
a. Spell check!
b. In Section 3, be consistent, define abstract syntax and then an 
example or only do the example. I think for a primer, the example is 
sufficient. However, I could see a case to include both.
c. Be consistent in naming: If you say informationType, information type 
or Information Types, etc. It may be simpler to use the actual syntactic 
element to alleviate confusion. Example, Section 3.3.6.
c. Determine what person (first, third) for this document and revise.
d. Define briefly concept and business value, given any gotchas, and 
then an example.  This is different than describing exactly the syntax 
and instance around the concepts. However, it depends on your audience. 
If developers, the latter may be more familiar.

Section 3.3.3
a. In this section we talk about participants and roles. A role is 
equivalent to a behavior. Earlier we indicate in Section 3.3.1, that
roles and participants are synonymous. This is somewhat confusing. 
Suggest say there are related as the equivalence is more a role 
(roleType) to a behavior.
This is clearer in Section 3.3.3 than the short reference in the 
preceding section 3.3.1. Suggest you revise Section 3.3.1 or make a 
reference to later section.

Section 3.3.5
Identify the section where you define token, token locators, etc. 
because you give an informationType example here. This will guide the 
reader. This comment may be applied across the board.

Section 3.3.6
a. In several sections, and this is only one example, your key message 
is buried in a paragraph. For example in first paragraph, what is 
important (seemingly) is that:

"The tokens and their locators are used later on to define the identity 
attributes that ensure channel communication can be correlated."

Suggest you rearrange the sentence to show the value of this element 
then describe what it is.
For example:
"Tokens and their locators are used to define the identity attributes 
that ensure channel communication can be correlated. A token provides a 
mechanism for defining
an alias for an information type. Token locators can then be defined to 
locate this particular token from within a message type. Tokens and 
token locators are shown here to define channel types."

b. "The tokens we define will also be used to refer to a service 
reference, that is a url, t for a web service."
Delete errant 't.'

c. "The additonal information types that we defined earlier are needed 
because they are references in the token definitions and the locator 
definitions. And this is why weneeded to define them when we did."

Change to: The two informationType included earlier are used as 
references in the token and token locator definitions.

Note, this is an example how to optimize the words used.

Section 3.3.7
a. "Finally, having defined our roles, information types, tokens and 
locatorswe are in a position to define our channel."

locators we

b. "In our interaction that we presented earlier we have a channel 
variables called Buyer2SellerC. This channel variable has a type and it 
is that type that we shall now define. To define a channel we need to 
name it, we need to, optionally, describe it, we need to tell it which 
role realises it's behavioral interface (the role we send things to and 
receive things from). We need to provide a reference to a service and we 
need to imbue our channel type with some notion of how to derive it's 
identity when in use."

Change to:
In our interaction we have a channel variables called Buyer2SellerC that 
has a type. A channel is named, described, and then related to the roles 
that realize its behavioral interface.  A reference is provided to a 
service. The channel type will have the capability to derive its 
identity when in use.

c. It may be important to make the two key points on the identity and 
reference elements where you first introduce them - reference refers to 
a service and identity is valuable for correlation. See Section 3.3.5. 
Remember the key is provide a clear understanding of the use and value 
of these elements for choreography.

Section 3.3.8
You could simply say that to start to build your choreography, you need to:
 1. Declare relationships: Acts as an additional type check on channels 
used within the choreography.
 2. Define variables for information types and channel types.
 3. Define interactions and their order of sequence.

Then go to what detail is needed. Remember comment about clear 
understanding (not to be pedantic). Similar note on the succeeding 
paragraphs. Briefly describe how exchanges occur in interactions whereby 
information is included in variables that are relevant to the 
choreography.  Some of this may be better handled,
as previously indicated, in bullet format rather than the current format.

Received on Wednesday, 15 February 2006 01:22:08 UTC