Re: ACTION-479 completed: overview doc ready for review

On 07/08/11 16:02, Axel Polleres wrote:
> I have updated the Overview document...
>
>   http://www.w3.org/2009/sparql/wiki/Overview-Document
>
> In principle, my intention was a run-through all parts of the spec by a running example. this should be there now, touching all our docs (hope I didn't forget anything ;-) ) I hope this is sufficient as an entry point to our specs and a bit more appealing than only a plain bullet list of specs.
>
> This is still on the wiki, since AFAIR there was some process to turn TR template documents into spec-ready html (sandro?)
> if not, I can convert it manually to xmlspec, but that's not the major concern.
>
> Comments welcome! If it's good to go, maybe we can publish it together with Fed query...
>
> Axel

Apologies for doing this review in a rush.

I think the document needs some work if this is to be LC.

The overview document is a chance, and needs, us to coordinate across 
all the documents.  We should not hold up federated query and protocol 
while we sort things out.

The example comes across as forced - it does not always serve the needs 
of each area.

Whether it's named graphs or not needs sorting out - I suggest not, as 
it adds nothing but an extra level of detail yet is not new to SPARQL 1.1.

== Across docs:

I took a look at how we are presenting the overall work of the group by 
looking in each document

Query and Update have this list in the SOTD (Status of the Document) so 
it's very near the top.

SPARQL 1.1 Query
SPARQL 1.1 Update
SPARQL 1.1 Protocol for RDF
SPARQL 1.1 Graph Store HTTP Protocol
SPARQL 1.1 Entailment Regimes
SPARQL 1.1 Service Description
SPARQL 1.1 Federation Extensions
SPARQL 1.1 Conformance Tests
SPARQL 1.1 Query Results JSON Format (to be published)
SPARQL Query Results XML Format

Protocol has nothing yet.

Graph Store protocol has in the intro:

   Query
   Update
   Protocol
   Results XML
   Service Descriptions

Entailment has the main list, with entailment first, in the intro, below 
ToC.

Service Description has nothing.

Federated query has nothing.

Result/JSON has this list in the SOTD

Results/CSV-TSV has this list in the SOTD

Proposal:
All documents, in the SOTD, puts the list above, modified by putting the 
self document at the top.

Rationale:
My recollection is that we decided to have the same list and this was 
it.  Putting the particular document first makes sense.  Having it in 
the SOTD makes it easily accessible as the TOC can be quite long.

My experience in looking for W3C docs has been that I can find nearby 
docs quite easily with google so quickly getting to the right doc is useful.

Corollary:
Overview document follows the same order.

Originally, a year ago
   http://lists.w3.org/Archives/Public/public-rdf-dawg/2010JulSep/0260.html

I suggested that the results forms go higher, but the order we have now 
(I thought) decided) in the LC docs is better as it is focused at 
application developers, especially where they might need several docs.

No order is perfect because there are different perspectives and we all 
want our own document to get good prominence but not putting "Update", a 
wholly new part of SPARQL,  at slot 2, feels odd.

==== Comments on the Overview document:

Back then I also noted:

"The wiki overview document seems to get into some complexity rather
early."

This is still true.

I don't think putting federated query, which is optional (the Overview 
doc does not mention this) so high up works.  Same for entailment over 
update and protocols.

"SPARQL 1.1 Uniform HTTP Protocol for Managing RDF Graphs"
=>
"SPARQL 1.1 Graph Store HTTP Protocol"

----

Single data for all examples:

This does not work for me.  It's too shaped by the need to apply to 
every doc, not the need of each doc on its own.

----

Please reformat the Turtle and make it legal FOAF (mailto:)

@prefix :        <http://example.org/alice#> .
@prefix rdfs:    <http://www.w3.org/2000/01/rdf-schema#> .
@prefix foaf:    <http://xmlns.com/foaf/0.1/> .

:me
     a           foaf:Person ;
     rdfs:label  "Alice" ;
     foaf:knows  <http://example.org/marie#me> ,
                 <http://example.org/charlie#me> ,
                 <http://example.org/bob#me> ;
     foaf:mbox   <mailto:alice@example.org> .

<http://example.org/charlie#me>
     foaf:mbox   <mailto:charlie@example.org> ;
     foaf:name   "Charlie" .

<http://example.org/bob#me>
     foaf:name   "Bob" .

<http://example.org/marie#me>
     foaf:name   "Marie" .

----
This looks like named graphs:

"""
Graph: http://example.org/alice

Graph: http://foaf.example.org/
"""

which is distracting - it's even used as named graphs sometimesplace 
(Update, graph store protocol) but not in others (query, entailment).

== Query:

Does not illustrate anything from SPARQL 1.1

Giving the graph URIs confuses the issue.
Named graphs are not used in the query example.

Suggest:
?P ->> ?person
?N ->> ?name

-----------------
=== Federate query

Federate query is optional.
The example does not work for real.

-------------------
== Entailment

Query has no PREFIXes
Drop the FROM clauses
Why not pull in the real FOAF schema?

Show the results.

"""
If the data of both graphs 'http://www.example.org/alice' and 
'http://foaf.example.org/ are stored in an RDF Schema aware RDF Store.
"""

?? It's whether the query is executed with entailment that matters, not 
the store??

== Update

The example data didn't use bNodes.

Why is it a named graph when the query example didn't use named graphs?

Named  graphs are only there to make the "Graph Store Protocol" work but 
that can use ?default.

== Graph Store Protocol

HTTP request is wrong - need a blank line.
Better is "text/turtle;charset=utf-8"

Turtle is broken - no @prefix for ":"

The example should show PUT then GET.

	Andy

Received on Monday, 8 August 2011 11:41:15 UTC