[comments] typo and general

Comments about the specification:

SPARQL Protocol for RDF
W3C Working Draft 14 September 2005
http://www.w3.org/TR/2005/WD-rdf-sparql-protocol-20050914/

There are quite a lot of typos and spelling mistakes in the document,  
please check it before next publication.
http://www.w3.org/2002/01/spellchecker?uri=http://www.w3.org/TR/2005/ 
WD-rdf-sparql-protocol-20050914/

The document seems unfinished in many places. :/



* Abstract:
Could you make it clearer?
     "SPARQL is a query language and protocol for RDF. This document  
specifies the SPARQL Protocol for RDF; it uses WSDL 2.0 to describe a  
means for conveying SPARQL queries to an SPARQL query processing  
service and returning the query results to the entity that requested  
them. This protocol was developed by the W3C RDF Data Access Working  
Group (DAWG), part of the Semantic Web Activity as described in the  
activity statement ."

I would removed the last sentence too which is not the abstract of  
the document.  I would make SPARQL with a link to the appropriate  
specification or a primer. I think a Primer would be great for this  
two specifications. A proposal that can be certainly improved.

     [SPARQL][1] is a [query language for RDF][2] and a protocol
     for RDF. This document specifies the SPARQL Protocol for RDF;
     it defines how to convey SPARQL queries between a query client
     and a query processor. The SPARQL protocol is defined by
     [WSDL 2.0][3].

I'm not a native English speaker, I'm pretty sure it could be improved.



* Dependencies:
     There are dependencies of SPARQL Protocol on four documents  
which are at WD stage. You might want to strongly coordinate with  
these groups. Do you know when WSDL 2.0 is expected to reach  
Recommendation status? I would also recommend that you move forward  
the two documents together and synchronized.



* Test Suite:
     Is there a test suite defined for SPARQL Protocol. I haven't  
found any traces in this document.



* QA Spec GL ICS
     See my other message about checking for fundamental QA  
principles. It's quite rare to see a document like this one these  
days at W3C. It fails on many points elementary requirements.




* Examples/Graphics/Links
     Example in the section 2.1 or more context might be helpful to  
understand what you are talking about. The document is often very  
hard to understand. For example, you start the section two with:

     [[[
     SPARQL Protocol contains one interface, SparqlQuery,
     which in turn contains one operation, query.
     ]]]

What is an interface?
What is an operation?
The power of appropriate hypertext is also interesting in this case.  
The WG has written:

     [[[
     SPARQL Protocol is described abstractly  with WSDL 2.0
     [WSDL2] in terms of a web service that implements its
     interface, types, faults, and operations, as well as by
     HTTP and SOAP bindings.
     ]]]

with the link on "described abstractly". I would have done:

     [[[
     "WSDL 2.0 [WSDL2] description of SPARQL Protocol" is
     given abstractly in terms of a web service that implements
     its interface, types, faults, and operations, as well as by
     HTTP and SOAP bindings.
     ]]]

with the link on "WSDL 2.0 [WSDL2] description of SPARQL Protocol"  
which is better for the semantics and search engine indexing.

Later in the document, again:

     [[[
     This interface and its operation are described in the
     following WSDL 2.0 fragment (from sparql-protocol-query.wsdl,
     which contains the relevant namespace declarations):
     ]]]

prefer

     [[[
     This interface and its operation are described in the
     following WSDL 2.0 fragment (from "WDSL 2.0 description of
     SPARQL Protocol", which contains the relevant namespace
     declarations):
     ]]]

Is it normal the double period in the documentation section of WSDL  
2.0 profile.

I'm not sure I would have called figure the "Figure 1.0", maybe excerpt.

in 2.1.2
text "defined" linked to http://www.w3.org/TR/rdf-sparql-query/ 
#grammar. again choose an appropriate word which is meaningful when  
creating a link. In this section two, you are using [SPARQL] coming  
from nowhere with no intent to be a reference. Use only SPARQL and  
not SPARQL if there's no link.

in 2.1.3, the words "ASK" and "SELECT" are linked to SPARQL Protocol  
but with no specific destination.

Another link problem

     [[[
     The query-result type is defined in this W3C XML
     Schema fragment, from sparql-protocol-types.xsd:
     ]]]

prefer

     [[[
     The query-result type is defined in this fragment, from "W3C XML
     Schema for SPARQL Protocol":
     ]]]

in 2.1.4
     [WSDL2-Adjuncts] defines several…
     no link on WSDL2-Adjuncts what is it?

and many others.


* CSS Style for code
     underlined style for "code" element is not that much appealing  
visually and with a smaller font.




* Normative references to XML Schema?

     [[[
     Abstractly, the contents of the In Message of
     SparqlQuery's query operation is an instance of an
     XML Schema complex type, called st:query-result in
     Figure 1.0, composed of two further parts: one SPARQL
     query string; and zero or one RDF dataset descriptions.
     ]]]

Is it a normative reference to XML Schema?


* Reference without context:

There are references to this document at least four times and without  
context.
     http://www.w3.org/2001/sw/DataAccess/rq23/


* HTTP Example.
    Very good part of the specification. But I guess it's not  
normative so you should say so. There are example of SPARQL query but  
no example of the document on which they apply at the start. That  
might be helpful to understand the example completely.


* example.org,com,net are official domain names for examples.
This
     http://my.example/…
to change by
     http://my.example.org/…


* mime type:
Where the mime types come from?

     * application/sparql-results+xml
     * text/rdf+n3

Are there official? If not you might say so.



* CSS for the document:
I have sent a previous mail just before publication on how to improve  
the stylesheet for this document. Could you implement it? Eric had  
approved it if I remember. See my message in this list on 13  
September 2005 with the attachment.



[1]: link to a primer
[2]: http://www.w3.org/TR/rdf-sparql-query/
[3]: http://www.w3.org/TR/wsdl20/

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

Received on Wednesday, 12 October 2005 02:15:52 UTC