Re: RDF Primer Typo

Markus,

Responses inline. Not: given the time constraints I changed only the 
ones I thought were most pressing,

On 21-02-14 15:18, Markus Lanthaler wrote:
> On Wednesday, February 19, 2014 11:38 PM, Guus Schreiber wrote:
>>>> I wouldn't start the introduction with  a note which more or less
>>>> repeats the abstract, I would instead add the reference to RDF11-NEW
>>>> after the first "real" sentence.
>>
>> Moved Note to abstract, but keeping the Ref to rdf-new in there.
>
> I'm not a big fan of references in the abstract (especially references to
> specific chapters). I would suggest to just remove "Secs. 3-5 can be used as
> a minimalist introduction into the key elements of RDF", it's obvious from
> the documents title, and (optionally) move "Changes between RDF 1.1 and RDF
> 1.0 (2004 version) are summarized in a separate document: "What's New in RDF
> 1.1" [RDF11-NEW]" to the Introduction.

Left unchanged.

>>>> Concrete RDF syntax is introduced later in Sec. 5. -> syntaxes are!?
>>
>> I don't like "syntaxes"; I will also try to get rid of that plural form
>> in other place.
>
> Fair enough, maybe using "language" (as in Turtle languages), "formats",
> "serialization formats" or something similar would be better then!? It's
> also fine for me if you prefer to leave it as is.

Changed to "languages" and "serialization formats", except where it is 
placed opposite "abstract syntax".

>>>> I noticed that you define quite a number of terms but never reference
>>>> them. I was for example wondering if resource was already defined in
>>>> section 3.1 and had to manually go back to the introduction to find
>>>> that out. Especially for new comers I think it would be very helpful
>>>> to explicitly cross-reference all these terms.
>>
>> Maybe that would have been nice, although this is more useful in a
>> normative document like Concepts.  Will do this later, time permitting.
>
> I disagree. Especially newcomers unfamiliar with the terminology will often
> need to jump back to a term's definition.

Added a few more links to Concepts: datatype, graph name, language tag. 
I was out of for the rest, sorry.

>>>> Section 3.3
>>>> Literals are basic values that are not IRIs -> neither are blank
>> nodes!
>>
>> Changed to "Literals are basic values that have no IRI". In this way it
>> is not phrased as a logical complement and is unlikely to confuse
>> readers.
>
> Hmm... better but still a bit confusing. What about "Literals are basic
> values such as strings, numbers, etc." (no need to mention IRIs).

The next sentence says this already (numbers, strings). Left unchanged.

>>>> Shouldn't "datatype" and "language tag" be definitions instead of
>>>> just being formatted in italic?
>>
>> See above.
>
> What are you referring to? That definitions are more useful in a normative
> document? That doesn't matter here. It's a matter of consistency and style.
>
>
>>>> Section 3.5
>>>> The IRI associated with the graph is called the "graph name" ->
>>>> graph name should be formatted as definition
>>
>> See above.
>
> See above :-)
>
>
>>>> Section 4
>>>> Instead, the example (in prose) from the second paragraph could be
>>>> included in triple form (basically example 5, but using the same
>>>> IRIs as in the prose)
>>
>> I prefer to keep the examples in the spirit of Sec. 3, and only have
>> concrete syntax examples in Sec. 5.
>
> Example 4 (in section 3) already uses IRIs for everything but predicates.
> Since you introduce RDF Vocabularies here and rdf:type etc. in the table I
> think it would just be consequent to reuse them in Example 5. But I'll leave
> it to you.

Left unchanged.

>>>> Section 5.1
>>>> Overall, I'm wondering if it really makes sense to explain the "Turtle
>>>> family of RDF languages" in so much detail. The only question that the
>>>> reader will ask himself is why are there four? How do I know to choose
>>>> which? These questions are not answered at all IMO. I would like to
>>>> shrink this section considerably.
>>>>
>>>> The three pages (when printed) could probably easily be reduced to 1,
>>>> max 1.5 pages without losing much. The only difference between
>>>> N-Triples and N-Quads is the fourth component. That could be said in
>>>> one sentence and be shown with a single example (default graph).
>>>> Basically the same is true for TriG and Turtle.
>>
>> I do not agree. I think the current treatment is about the right
>> length.
>
> OK, we agree to disagree :-)
>
>
>> Rationale for each syntax is stated (see final pars of
>> N-Triples/N-Quads, and remarks on multiple graphs for TriG). This was
>> also the reason to present them as a "family".
>
> It just says that it is often "used for exchanging large amounts of RDF and
> for processing large RDF graphs with line-oriented text processing tools".
> My "critique" was that it doesn't tell a novice when to use which language.
>
>
>> If you ask me: would it have been better to have one "Turtle family"
>> language (name), then I would have said yes, but that ship sailed a
>> long time ago.
>
> +1000
>
>
>>>> Section 5.2
> [...]
>> OK, this example is indeed better. Will change accordingly, with
>> explanatory text
>
> Great. Looks much better IMO. There's just a minor thing in the description:
>
>    The @id keyword, when used as a key in a JSON-LD document, points
>    to an IRI identifying the resource corresponding to the parent
>    JSON object.
>
> You have to say that, when used in the body of a JSON-LD document (not in
> the context), the @id keyword sets the IRI identifying the resource
> corresponding to the *current* JSON object. Not the parent one! Otherwise
> Mona Lisa's @id would set the IRI of Bob's JSON object.

Changed as suggested.

>> To prevent people having to read through a very long Sec. 5 (which is a
>> long-standing worry from me, as you know) I have added a reading tip to
>> the start of the section:
>>
>> [[
>>     Tip: we suggest to read Sec. 5.1 on the Turtle-related syntaxes and
>> to read the sections on JSON-LD, RDFa and RDF/XML only when you are
>> interested in that particular usage of RDF.
>> ]]
>
> OK, it should also provide a rationale (because you explain basic concepts
> in Section 5.1) so that the other languages aren't perceived as "second
> class" formats. IMO, the simplest thing however would be to just remove it
> to avoid wrong conclusions.
>
>
>> Response to the JSON-LD part will follow in a separate message.
>>
>>>> Section 7
>>>> A large amount of RDF data is available as part of the Linked Data
>>>> [LINKED-DATA] cloud. -> the reference doesn't help here. Either
>> remove
>>>> it or link to http://lod-cloud.net/
>>
>> The ref is explicitly to Linked Data, not to the cloud. Another
>> problem: the link you mention is not maintained currently.
>
> Then maybe it's better to rephrase it as
>
>    "A large amount of RDF data is available as Linked Data [LINKED-DATA]."

Changed as suggested.

>>>> The paragraph and example of sameAs doesn't belong here IMHO. Either
>>>> move it to the previous section (Semantics) or simply remove it.
>>
>> I don't agree. Linking datasets is key in linked data, and sameAs plays
>> a central role there.
>
> It is by far not the only mechanism to link datasets and is the root for
> *many* problems. owl:sameAs needs a good understanding of what really
> happens to be used properly. I would argue that it's not something for
> newcomers and would thus really prefer to remove it.

I think important and intuitive enough to leave in. Left unchanged.

>>>> Section 8
>>>> Could be remove completely IMO.
>>
>> Disagree. Some sort of (short) conclusion is good practice in my book.
>
> Agree if there is something to be said. If there's nothing, just leave it
> out.
>
>    "This concludes our brief introduction into RDF. Please consult the
>     references to get more detailed information. You might also want
>     to take a look at the W3C Linked Data page."
>
> ... doesn't say much but if you prefer we can also leave it in.

Left unchanged.

Thanks again for the comments!
Guus

>
>
> It's a great document. Good work!
>
>
> Thanks,
> Markus
>
>
> --
> Markus Lanthaler
> @markuslanthaler
>
>
>
>

Received on Monday, 24 February 2014 11:50:46 UTC