[selectors-api] Editorial

Hi,
This is a QA Review comment for "Web Services Description Language (WSDL) Version 2.0: RDF Mapping"
http://www.w3.org/TR/2006/WD-wsdl20-rdf-20060518/
2006-03-27
Last Call WD

About http://www.w3.org/TR/2006/WD-wsdl20-rdf-20060518/

We notice that we are late for the review and we apologize for this. 
Jonathan Marsh [encouraged][1] us to do the review anyway.

[1]: http://lists.w3.org/Archives/Public/public-ws-desc-comments/2006Jul/0006

These are editorial comments and suggestions, not really issues per se.

* Introduction

1.   "Web Services Description Language is defined in XML, because XML is the standard format for exchange of structured information."

 s/the standard format/a common format/
 Reasoning: this email is a structured information and is expressed as text but with a structure of type: 
  "Header: information"

2. "The use of XML brings better interoperability to WSDL generators and parsers, and the use of XML Schema makes the structure of WSDL well constrained, yet extensible."

 "better interoperability"? Is it really true? in which ways? Better interoperability is achieved when a format is implemented and used by many vendors in a market. But again this email in text as many implementations and is not XML. Maybe there is a better way to express it, something like "WSDL generators benefit of the wide avaibility of XML parsers".
 In addition, later on in the same paragraph, the prose says the opposite by "little interoperability can be expected" ;) 
 
3. "in general don't have"

 s/don't/do not/
 better in written English and less prone to misunderstanding.
 
4. "XML vocabularies in general don't have clear composition rules"
 
 XML fans will not like this sentence. ;) Thy will reply right away. They are clear composition rules!!! It's defined by the prose in the specification. Maybe what you want to say if I understood the sentence is that "XML vocabularies do not embed in the language itself the information, which is necessary for mixing vocabularies without human interaction." Or something similar.

5. "In contrast, the Semantic web requires knowledge from many different sources to be easily combined so that unexpected data connections can be used. For this purpose there is the Resource Description Framework (RDF), whose graph structure together with the use of URIs for identifying nodes makes it very easy for different documents to be brought together. If a WSDL document describes a Web service, a policy document attaches constraints to the service and a general description specifies the author of the service, all this information can be merged and the resulting document will contain all the three kinds of information associated with the single service."

 This whole paragraph needs rewriting to really make it clear, which is not the case now. Think about each sentence, make very clear statements, short sentences. Maybe write down on a paper in terms of a list what you want to express. Do not start by "in contrast", but more in a way that shows the additional benefits. There is the XML Services and on top of that if we use RDF, we gain this and that.
 The prose also  uses the word "constraints". It's not a very positive statement. A constraint is maybe in fact an additional set of information helping a service to operate. It makes it easier to process the information not more constraining ;) A question of (human) semantics…
 
6. The Note.

 It's good to have the note about expected knowledge. Maybe you could add a few links to different materials or even better a help page somewhere on the W3C Web site with a short introduction and a list of good materials to read to be able to start.

 Side Note: That would be good to have someone from the WG to write a short article for the QA Weblog (http://www.w3.org/QA/) about the benefits of WSDL-RDF with a concrete use case. Intended audience would be students, journalists, or curious learners (WSDL-RDF 101). Something very short, and I will help for graphs and prose.

7. HTML Markup

 The use of HTML Markup doesn't seem adequate (right semantics) in many cases. For example, the editors have used element "tt" when maybe something like "var" or <code class="wsdl">…</code> would have been better. 

8. References to external documents

 Not mandatory but helpful for the reader, it can be sometimes good to link directly to the appropriate part of the specification you are referring to. For example, in 
 "WSDL component model defined in [<a href="#WSDL-PART1">WSDL&nbsp;2.0 Core
 Language</a>]"
 Put also a link on WSDL component model directly to the appropriate section in WSDL 2.0 Core.
 
9. Internal references

 Sometimes, the editors have given references to other part of the specifications. For example,
 
 "This section may also briefly touch on some differences between the OWL ontology and the component model, but for the full account and rationales of these differences see section 4."

 It will be better to write these references that way:
 
 "This section briefly touches on some differences between the OWL ontology and the component model, but for the full account and rationales of these differences, see section 4. <cite><a href="#modelingdiffs">Differences from the WSDL Component Model</a></cite>."

8. Innapropriate use of long dash

 For example in "The top-level WSDL component — description — is mapped to a single instance of the class Description"



-- 
Karl Dubost - http://www.w3.org/People/karl/
W3C Conformance Manager, QA Activity Lead
   QA Weblog - http://www.w3.org/QA/
      *** Be Strict To Be Cool ***

Received on Wednesday, 9 August 2006 03:35:10 UTC