Re: http://lists.w3.org/Archives/Public/public-ws-chor/2006Feb/0008.html

From: Monica J Martin <Monica.Martin@Sun.COM>
Date: Tue, 14 Feb 2006 17:22:06 -0800
To: "'WS-Choreography List'" <public-ws-chor@w3.org>
Message-id: <43F2823E.5070603@sun.com>
Subject: 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!
DONE

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.
TO DO

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.
TO DO

c. Determine what person (first, third) for this document and revise.
TO DO

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.
TO DO

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.
DONE

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.
DONE

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."
DONE

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."
DONE

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.'
DONE

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.
DONE

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
DONE

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.
DONE

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.
DONE

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.
DONE

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.
DONE - partially

Received on Monday, 17 April 2006 13:00:32 UTC