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

Hi Andy,

Thanks for the feedback.

1) I am fine to publish this as FPWD (agreed that this should go through some iterations of feedback before we mark it LC), which should allow us to publish this along with the other docs.

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

How about simply *only* referring to the Overview document and use this as the single entry point? 
Something like instead of putting the full list in each document, just put:

"SPARQL 1.1 is a set of specifications that provide languages and protocols to query and manipulate RDF knowledge on the Web or in an RDF store. The SPARQL 1.1 Overview [SPARQL11-Overview] lists all these documents and describes how they interplay."

I would not consider this a problematic change in the current LC documents. 

As for the order, it is true that the order in the overiew doc is different from those lists in the currrent docs. 
I found the order more logical for the purpose of the overview document, i.e. presenting the standards one by one 
by a short example.

More comments inline below.

Axel

On 8 Aug 2011, at 13:40, Andy Seaborne wrote:

> 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.

Hmmm, we can put them later, my impression was that this order would
provide a more coherent storyline.

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

fixed.

> ----
> 
> 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.

Can you give me some more concrete hints why this doesn't work?


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

mailto: now fixed. 

As for Turtle shortcuts, I didn't use them, since I didn't 
want to pre-assume them, but I also don't feel strongly about that. 

> @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).

I added explicit FROM clauses in the query, federated query and entailment examples 
which make this clearer now, I hope. Apart from that, I don't find it too critical, since I don't 
mention named graphs anywhere explicitly. The details of datasets is not relevant at this level 
for a new reader, and the intuitions of the syntax should be clear with those, IMHO.

> 
> == Query:
> 
> Does not illustrate anything from SPARQL 1.1

True, but that was not the intention, the intention was only to say "this is what SPARQL1.1 query language is for"
I added a sentence to make this claerer: 

Compared to earlier SPARQL1.0 specification [SPARQL1.0] from 2008,  SPARQL1.1 adds a number of new features to the query language, including subqueries, value assignment, path expressions, aggregates, etc.


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

Added an explicit FROM clause now, see above.

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

fine with me, changed that.

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

Well, yeah, that is a problem... since DBPedia returns (with good reason) only limited results... Any idea for a working, but not necessarily more complicated query?

> 
> -------------------
> == Entailment
> 
> Query has no PREFIXes

fixed.

> Drop the FROM clauses
> Why not pull in the real FOAF schema?

without the FROM clauses, I am not sure how I can merge necessary ontological the information into the data graph.
(since two FROM clauses merge the default graph)

> 
> Show the results.
> 

added results in the Entailment section...

> """
> 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??

... and rewrote that.

> 
> == Update
> 
> The example data didn't use bNodes.

right, I will remove those.
> 
> 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.
> 

good point, I can change that.

> == 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.

hmm, this is just to give one small example where a triple is inserted, which needs POST, right?
Why/where should I show PUT/GET? Wouldn't that go into too much detail. 

thanks again for the comments,
Axel




>         Andy
> 
>

Received on Monday, 8 August 2011 16:08:00 UTC