(editorial/QA) Notes on WS Choreography model overview (2004-03-24 WD)

Dear WS-Chor WG,

Here are a few notes and comments on the first public working draft of  
the WS Choreography Model Overview document. Analysis of the draft  
document was made with QA in mind, and comes from someone without  
advanced knowledge of Web Services.

Generally speaking, the document is very easy to read, even for someone  
without particular knowledge of WS choreography, and especially for a  
first draft. With regards to the goal of introducing the topic to its  
audience, the document is a success.

[QA: Status]

Speaking of goal and scope, however, it is not altogether clear what  
the WG is aiming at with this document. The status only states that it  
[[ is not a chartered deliverable of the Web Services Choreography  
Working Group; however, it is the corner stone of the Choreography  
Definition Language, which is a chartered deliverable.]] Which in  
itself is fine, we know what the document is not, but not really what  
it is. At times it feels like a primer, at times like a requirements  
document, and at times, like a technical specification.

[QA: Conformance]

The document would thus benefit from a clear definition of its status  
and goal. Specifically, is it made to be implementable? Or is it just  
an informative overview?

Unless its final status is a NOTE, this documentation will have to be  
implemented. It would be a good move to make its structure evolve  
towards a better definition of what is normative and what is not, what  
it means to conform to the document (the addition of a conformance  
section would be a first good step. Another step, when the conformance  
model is defined, will be to clarify how testing will be done...

[QA : informative vs Normative]

One particular aspect of making the document implementable will also be  
to clarify the usage of the diagrams. These diagrams are relatively  
clear and useful (in spite of not having a decoding guide, which should  
certainly be added), and they offer a graphical representation of the  
associated text. Or does, in fact, the text offer an explanation for  
the diagrams? How do you guarantee that both are equivalent (still  
keeping implementation in mind here)? Hardly feasible, perhaps. But  
then which holds the normative status, which the informative?

Generally speaking, a sound practice would be to clearly mark normative  
and informative parts of the document. The document holds a lot of  
examples (which is great) but that might dilute the  
implementable/testable content.

[QA: dependencies]

Another point probably worth clarifying in future versions is the  
dependencies with other documents. I assume this will be addressed with  
an eventual clarification of the status.

The current draft already has hints of dependencies definitions (e.g  
Compatibility with other Specifications. in 1.2) but it seems to lack  
formal definitions of the dependencies. The document states this  
overview will [[work alongside and complement]] other specifications.  
But How? Granted, the answer is partly available within the bulk of the  
document (e.g [[An Interaction always involves the exchange of  
information between two Roles in a Relationship that conform to a  
Message Exchange Pattern as defined by WSDL 1.2.]]). It might be a good  
idea to explain your dependencies and relationship model in more  
details.

In a possibly related note, I found myself asking a few time "yes, but  
how?" when the documents states "this can do that". e.g [[An Import  
statement can contain references to a complete Choreography or part of  
a Choreography.]] in 3.3.2. This might, however, come from a lack of  
understanding of the technology, but if the "how" will be explained  
elsewhere, the specification should refer to that.


[Editorial]

As I wrote earlier, the document is particularly clear and readable. At  
times, however, the phrasing tends to be long and awkward. e.g [[It's  
purpose is to provide an information model *that* describes the *data*  
and the relationships between them *that* is needed *to* define a  
choreography *that* describes the sequence and conditions *in which*  
the data exchanged between two or more participants *in order to* meet  
some useful purpose.]]
As a native french speaker I am often reminded that the French tend to  
use and abuse subordinate clauses when writing in english... Not  
calling anyone french, obviously, but the text of the specification  
tends to suffer from this trend, too. Using shorter sentences and  
strict structures might be a good idea.
Also, in the sentence above: purpose... purpose is a bit awkward.
Also: s/It's/Its/

in 1.2: s/participants take part in/participants in/

There are a couple typos (an ampersand missing in 3.4, and  
"choreogaphy")
	http://www.w3.org/2002/01/spellchecker?uri=http://www.w3.org/TR/ws- 
chor-model/
This tool actually seem to stumble on quite a few acronyms, you may  
want to use proper markup to expand them, and include a glossary of  
concepts introduced by the specification (especially important for an  
overview, I reckon).


I hope these comments will help you make this document a very good  
specification. Feel free to contact me if any comment I made was not  
clear enough.

Regards,
-- 
olivier Thereaux - W3C / QA
http://www.w3.org/People/olivier/