Issue 097 - WS-C: Editorial comments

[Ram Jeyaraman <Ram.Jeyaraman@microsoft.com>]

This issue is identified as 097.

 

Please use the subject line for future correspondence on this issue: "Issue 097 - WS-C: Editorial comments".

 

From: Ram Jeyaraman [mailto:Ram.Jeyaraman@microsoft.com]
Sent: Sunday, October 15, 2006 7:24 PM
To: ws-tx@lists.oasis-open.org
Subject: [ws-tx] NEW Issue - WS-C: Editorial comments

 

Protocol: WS-Coordination

 

Artifact:  spec
 
Draft:  WS-Coordination specification PR 01
 
Link to the document referenced: http://www.oasis-open.org/committees/download.php/20241/wstx-wscoor-1.1-spec-pr-01.doc 

Section and PDF line number: See description below.

Issue type: Editorial

Related issues: None
 
Issue Description:

1.       Section 1.3

a.       Need bullets for the two items (lines 47 and 48) the “framework allows for”.  These were present in the contributed specs.

b.      Typo:

                                                                           i.      Before: “isolation-level supported signatures or other information”

                                                                         ii.      After: “transaction isolation levels or other information”.

2.       Section 1.3 Extensibility
Minor editorial comment.  Lines 52-53:  “To understand the syntax used in this specification, you should be familiar with the WSDL [WSDL] specification, including its HTTP and SOAP binding styles.”   Proposed revision:  change from ‘you’ to ‘the reader’.

3.       Section 1.4 Terminology
> Namespace URIs of the general form "some-URI" represents some application-dependent or context dependent URI as defined in RFC3986 [URI].
This feature is never used in this specification.  Remove text from the specification.

4.       Section 1.6, replace line 92-93 with “The XML schema and the WSDL declarations defined in this document can be found at the following locations:”

5.       Section 1.8 Normative References. Use correct SOAP version 1.2 link is http://www.w3.org/TR/soap12-part1/.

6.       Section 2

a.       Lines 150 – 153 is a bit misleading; one may read it as “participants register using application-defined mechanisms”.  Perhaps breaking the sentence as follows might help: “CoordinationContext elements are propagated to parties which may need to register Participants for the activity. Context propagation may be accomplished using application-defined mechanisms -- e.g. as a header element of a SOAP application message sent to such parties.”

b.      Line 93 - consistency:

                                                                           i.      Before: “Coordination context”

                                                                         ii.      After: “CoordinationContext”

7.       Section 3.1

a.       Two instances of a typo:

                                                                           i.      Before: “The structure and semantics of this message is defined in”

                                                                         ii.      Before: “The structure and semantics of this message are defined in”

b.      Line 259 nit - double-spacing after “Optional.”

8.       Section 3.2.2

a.       Line 382 - typo:

                                                                           i.      Before: “contains the coordinators Endpoint Reference”

                                                                         ii.      After: “contains the coordinator’s Endpoint Reference”

9.       Section 4

a.       Line 416 - is it really correct to refer to [Reason] as “the English language reason element”?  Suggestion: Change to “[Reason] a human readable explanation of the fault”.

10.   Section 4.1 and 4.2

a.       Line 458 and 466 – typo:

                                                                           i.      Before: “the endpoint that generates”

                                                                         ii.      After: “the endpoint that generated”

11.   Section 4.4 and 4.5

a.       Nit – the font seems to change in these sections. Use the same fonts as in other sections.

12.   Several examples use the myApp prefix but this is not defined in this section. (> xmlns:myApp="http://fabrikam123.com/myApp"). Note as well that it would be better if this was based on http://www.example.com/ e.g http://www.example.com/myApp.

13.   Section 1.4 Terminology had the usual description of the “MUST”, “MAY” etc. but the text repeatedly uses “may” (lower case). Check the use of ‘must’ and  consider whether this is intentional throughout the doc.

14.   The WS-AT spec uses a Courier New font for XML elements within the text (e.g. “Specifically, the <wscoor:CoordinationContext> header”) but WS-Coordination never does. The use of the font aids readability.

15.   Appendix A. Acknowledgements.
Line 655: Jim Johnson (Microsoft) is missing in the acknowledgement section.
Check with Peter Furniss to use the right affiliation description.

16.   All bulleted items in the specification: Indent one level deep.

 

 

Proposed resolution: See issue description.