Re: Overview document

On 24 Aug 2010, at 10:27, Andy Seaborne wrote:

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

makes sense... I needed the FOAF example for entailment, bu I can hold off and just mention only the 
subproperty triple in the Entailment section.


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

So, you'd suggest to drop examples alltogether here?
My idea was to explain the role of all specs along one coherent example.

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

We need to decide/discuss whether we mention all or  just mention the 
Rec Track documents? (E.g. I assume the test suite will rather remain a note)


Axel

> 
>         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 11:30:50 UTC