RE: QA Review on WSDL 2.0 Part 1, Editorial comments

Thank you for the comment below, and for your patience with us in resolving it.  We tracked the comment below as Issue LC7 [1].  The editors have addressed the editorial matters you highlight below in their latest draft [2].

If you agree with our disposition of your comment, we'd like you to acknowledge it within two weeks; otherwise we will assume you are satisfied.  The WG plans to enter a second (short) Last Call period in the near future, and we invite you to review that publication as well.

[1] http://www.w3.org/2002/ws/desc/4/lc-issues/issues.html#LC7
[2] http://dev.w3.org/cvsweb/~checkout~/2002/ws/desc/wsdl20/wsdl20.html


> -----Original Message-----
> From: public-ws-desc-comments-request@w3.org [mailto:public-ws-desc-
> comments-request@w3.org] On Behalf Of Dominique Hazaël-Massieux
> Sent: Thursday, August 05, 2004 5:48 PM
> To: public-ws-desc-comments@w3.org
> Subject: QA Review on WSDL 2.0 Part 1, Editorial comments
> 
> Reviewing http://www.w3.org/TR/2004/WD-wsdl20-20040803/ (part 3)
> 
> Editorial issues:
> - section 1.3 (WSDL terminology) has only one item; I would find
> surprising that this specification only defines one new concept; e.g.
> a
> 'Web Service Component'  would probably deserve to be defined here;
> also, linking to the WS Glossary may be a good idea
> 
> - section 2's title is "Component Model" and uses these phrases a few
> times, but doesn't define it
> 
> - section 2 has most of the meaty stuff (the component model), but it
> is
> somewhat diluted by the XML serialization formalism; I wonder if
> moving
> the XML serialization in a different section (or in an appendix) would
> enhance the readability of the spec;
> 
> - I suggest marking up and styling appropriately (or maybe
> capitalizing?) words that are used in a very specific way in the
> specification; e.g. in 2.1.1 "At the abstract level, the Definitions
> component is just a container for two categories of components; WSDL
> components and type system components." would better read IMHO as "At
> the abstract level, the Definitions Component is just a container for
> two categories of component: WSDL Components and Type System
> Components"
> (I used capitalization in this case, but italicizing may work better).
> 
> - the document introduction still calls Part 2 "Message Exchange
> Patterns", although it's now called Predefined extensions
> 
> - the document refers to the language as "WSDL"; since WSDL has been
> available in several versions, I suggest using "WSDL 2.0" instead - if
> not everywhere, at least in the introduction
> 
> - in 2.1.1 "Note that it is RECOMMENDED that the value of the
> targetNamespace attribute information item SHOULD be a dereferencible
> URI and that it resolve to a WSDL document which provides service
> description information for that namespace"; the "SHOULD" is not
> needed
> since the sentence is preceded by "RECOMMENDED"
> 
> - I suggest linking the XPointer scheme definition for WSDL (appendix
> C)
> from section 2.1.1., where dereferenceability of components is
> mentioned
> 
> - there are only 2 examples of complete WSDL definitions in the whole
> spec (one in an appendix); adding a few simple examples in the course
> of
> the spec may help the reader a bit more; more generally, having a bit
> more illustrations of what WSDL is about would help [I see that a
> primer
> is in preparation; still, I don't think a few included examples would
> hurt]
> Also, the first example (in 2.7.1.1.1) should declare that
> <definitions>
> (and its children) are in the WSDL namespace
> The second example (in C.4) uses a relative URI as its
> xsi:schemaLocation; any reason to use "wsdl20.xsd" instead of
> "http://www.w3.org/2004/08/wsdl/wsdl20.xsd"?
> 
> - section 2.2.2.3 introduces the notion of style, which is only
> explained later in 2.4.1.1; would be good to make a link from the
> former
> to the latter
> 
> - section 2.4.2 reads "If the Interface Operation component uses a
> {message exchange pattern} for which there is no output element, such
> as
> 'http://www.w3.org/2004/08/wsdl/in-only'"; but according to the
> paragraph above "The RPC style MUST NOT be used for Interface
> Operation
> components whose {message exchange pattern} property has a value other
> than 'http://www.w3.org/2004/08/wsdl/in-only' or
> 'http://www.w3.org/2004/08/wsdl/in-out'.", this should not be "such
> as",
> but "i.e."; or did I miss something?
> 
> - 2.4.2.1 starts with "The wrpc:signature extension AII MAY be be
> used":
> what is AII? "be" is repeated twice
> thereafter, it uses the notion of a function signature, without much
> introduction; since "RPC" is never translated into "Remote Procedure
> Call", it looks a bit awkward
> 
> - in section 2.5.1 "by the global element declaration reference by the
> {element} property.", "reference" should read "referenced"
> 
> - section 2.8.2 reads "An OPTIONAL required attribute" which
> contradicts
> the model described in 2.8.1  where {required} is REQUIRED
> 
> - 2.17, "the combination of these two properties need not be unique" ,
> "need" should read "needs"
> 
> - in section 3, "W3C XML Schema Description Language" isn't a proper
> way
> to refer to XML Schema; use "W3C XML Schema" or 'W3C XML Schema
> language'
> 
> - section 4.2 uses "DOES NOT" (upper case), as if it was an RFC
> Keyword;
> IT'S NOT
> 
> - the document references XML 1.0 Second  Edition, while the third has
> been published earlier this year
> 
> - it also references outdated versions of XML Infoset and WebArch (see
> [1])
> 
> - the table of contents should use real markup, rather than &nsbp;;
> I've
> provided a patch to xmlspec for this purpose [2]
> 
> - a few typos: "compomnent", "dereferencible" (should be
> dereferenceable
> AFAIK), "implicitely" (implicitly), "requestor" (requester) based on
> the
> spell checker [3]
> 
> 1. TR references checker:
> http://www.w3.org/2000/06/webdata/xslt?xslfile=http%3A%2F%2Fwww.w3.org
> %2F2004%2F07%2Freferences-
> checker&xmlfile=http%3A%2F%2Fcgi.w3.org%2Fcgi-bin%2Ftidy-
> if%3FdocAddr%3Dhttp%253A%252F%252Fwww.w3.org%252FTR%252F2004%252FWD-
> wsdl20-20040803%252F&
> 2. http://lists.w3.org/Archives/Public/spec-prod/2004AprJun/0000.html
> 3.
> http://www.w3.org/2002/01/spellchecker?uri=http://www.w3.org/TR/2004/W
> D-wsdl20-20040803/
> 
> --
> Dominique Hazaël-Massieux - http://www.w3.org/People/Dom/
> W3C/ERCIM
> mailto:dom@w3.org

Received on Friday, 29 April 2005 23:04:08 UTC