RE: RDF Primer Typo

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.


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


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


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



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


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


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


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


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


It's a great document. Good work!


Thanks,
Markus


--
Markus Lanthaler
@markuslanthaler

Received on Friday, 21 February 2014 14:19:36 UTC