Overview document

 > I quickly drafted some short overview document stub [1] to see 
whether this is what we need... It's only drafted on the wiki for the 
moment...  before I put it in spec style/add it to CVS, let's agree on 
the general direction. My plan would be to have a mini-example 
illustrating what you find in each spec document and what you can do 
with the spec.

 >> "Overview", "Guide", or even "Primer"?

Yes - we need to be clear about the intent.

Just a short overview for the page that is the general URL for SPARQL 
docs and links to the documents would be the minimum.

OWL has an overview and a primer.  If someone one is willing and able to 
write a primer then great but I think it's not an insignificant amount 
of work.

RDF has concepts and a primer.

[1] http://www.w3.org/TR/rdf-primer/

One if the things I'd would appreciate for RDF and OWL is a simple 
jumping off point to all the docs in each series.

The wiki overview document seems to get into some complexity rather 
early.  Talking about multiple named graphs in the intro is a bit heavy. 
  If an example is to be given, let's stick to the simple and common 
cases : one graph, no named graphs.

Any examples will overlap with the query doc.  I'm not convinced one 
brief example is helpful - the title and a sentence or two about the doc 
should be enough to guide the reader.  One example seems to fall between 
more discussion of the content and the doc itself.

My suggested order of documents was:

SPARQL 1.1 Query
SPARQL Query Results XML Format
Serializing SPARQL Query Results in JSON
SPARQL 1.1 Update
SPARQL 1.1 Uniform HTTP Protocol for Managing RDF Graphs
SPARQL 1.1 Protocol
SPARQL 1.1 Service Description
SPARQL 1.1 Entailment Regimes
SPARQL 1.1 Common Functions Library
SPARQL 1.1 Test Suite

which was an attempt to group related docs together, starting with 
query, then results from query (I assert these being the main uses of 
SPARQL), then update, SPARQL services and entailment.  And the one I 
missed, tests.  Its unfortunate that a list means there needs to be 
somesort of sort. I didn't include F&R.

	Andy

On 24/08/10 00:59, Axel Polleres wrote:
>> Other possible agenda items: (hidden in 2010JulSep/0224)
>
> Thanks Andy for the input!
>
>> * An overview page giving details of the documents?
>>     Is this a REC track document? Something else?
>
> I quickly drafted some short overview document stub [1] to see whether this is what we need... It's only drafted on the wiki for the moment...  before I put it in spec style/add it to CVS, let's agree on the general direction. My plan would be to have a mini-example illustrating what you find in each spec document and what you can do with the spec.
>
> 1. http://www.w3.org/2009/sparql/wiki/Overview-Document
>
>> * SPARQL 1.1 Common Functions Library
>>     Status? Are we doing it? Document?
>>
>> * should move to promote the JSON format as a REC
>>     and canonicalise its name?
>>
>
> Good points as well, I would prefer to move them to next time, though.
>
> Thanks!
>
> Axel

Received on Tuesday, 24 August 2010 09:28:20 UTC