Re: Turtle document strategy [Was: Re: Review of Turtle doc (part 1)]

On 30/03/12 18:54, Eric Prud'hommeaux wrote:
> * Andy Seaborne<andy.seaborne@epimorphics.com>  [2012-03-30 15:43+0100]
>> ACTION-157
>>
>> First part of a review of the Turtle document, up to the ened of
>> section 5 (the Turtle grammar).
>>
>> I'm getting this out now because it covers the structure and
>> audience of the document and because it's already a bit long.
>>
>> 	Andy
>>
>> == General
>>
>> 1/ Audience:
>>
>> Who is the audience for the document?
>>
>>    Data authors?
>>    Parser writers?
>>
>> The doc, especially in the early sections, feels much more centered
>> on parser writers but I'd like to see it being for data authors with
>> parser writers material pushed towards the back in a "theory"
>> section.
>
> Traditionally, W3C priority is specifications over tutorials. Given
> the above choice, I'd say "Parser writers". That said, the intention
> was that the text be clear without sacrificing precision.

Respectfully, I disagree with this just a case of spec/parser writers, 
tutorial/data authors split.  This can be a spec for data authors.

A lot of this document is already targeted at data authors (sections 7 
and 11).  I see it as a matter of document organisation, not generating 
new material.  Example, put the examples and usage material after the intro.

>> 2/ Turtle? N-Triples?
>>
>> The document, especially in the earlier sections, talks a lot about
>> N-triples, e.g "Introduction" has an N-Triples example but no
>> Turtle.
>
> [[
> N-Triples triples are a sequence of RDF terms representing the
> subject, predicate and object of an RDF Triple. This sequence is
> terminated by a '.' and a new line (optional at the end of a
> document).
>
>    _:subject1<http://an.example/predicate1>  "object1" .
>    _:subject2<http://an.example/predicate2>  "object2" .
>
> N-Triples triples are also Turtle triples, but Turtle includes other
> representations of RDF Terms and abbreviations of RDF Triples.
> ]]
>
> The example is both N-Triples and a simple and expository form of
> Turtle, so I'm having a hard time aligning the comment with the text.

The document title is "Turtle".  The abstract does not mention N-Triples.

I was reviewing the version of 29/March - I see the document has changed 
in the last few hours ago in this area.

>> It reads almost like an Turtle/N-Triples comparison at times with
>> Turtle assumed background knowledge.
>>
>> It would be better to define Turtle, then to discuss N-Triples if
>> you want to frame N-triples as a simple subset of Turtle.
>>
>> The mixture, and comparing Turtle to N-triples (section 1 and 2), is
>> quite confusing.  (Alternative, start with writing down triples,
>> then introduce the Turtle syntax forms for better expression. But I
>> suggest the "describe Turtle, then N-Triples" approach.)
>
> We can't describe Turtle all in one go so I started with the simple
> forms, moving on to the alternate forms of terms and triple
> patterns. As it happens, the simple forms are exactly N-Triples so it
> made sense to either 1. label them specially to be referenced by a
> later N-Triples section, or 2. label them as N-Triples. Trying the
> first, the labels were pretty arcane (simple-triple,
> non-prefixed-absolute-IRI, datatyped-or-langtagged-literal) so I went
> with the second. Do you see a better alternative?

I've made suggestions in the comments below.  Changes to the document 
that I can see happening are improvements.

	Andy

Received on Friday, 30 March 2012 20:49:08 UTC