Re: RDF Primer Typo

On 19-02-14 13:28, Guus Schreiber wrote:
> Markus,
>
> Thanks for the comments. We're in the process of editing the document
> (some of your comments are actually planned changes). I expect to get
> back to you on Friday with a detailed response.
>
> Guus
>
> On 19-02-14 13:07, Markus Lanthaler wrote:
>> You might also have another look at all titles. I think the
>> capitalization is inconsistent. Some examples:
>>
>> Why *u*se RDF?
>> RDF Data Model  --> this should probably be "RDF's Data Model"
>> Blank *n*odes
>> Multiple *g*raphs
>> RDF *V*ocabularies
>> Writing RDF *g*raphs
>> Semantics of RDF *G*raphs
>> RDF *D*ata
>> More *I*nformation
>> Normative *r*eferences

Now done consistently:
- Title case for Level 1
- Sentence case for Level 2

>>
>>
>> Btw. Does it make sense to distinguish between normative and
>> informative references in an (informative) note? I don't think so.

Now only Informative references.

>> A few more remarks/suggestions since I'm already looking at the
>> document and think it will be one of the most important documents to
>> attract new users:
>>
>>
>> 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.

>>
>> Nitpicking but I don't like it when headers directly follow each other
>> such as 3. RDF Data Model -> 3.1 Triples. You could add a simple
>> sentence at the beginning of section 3 saying that RDF's underlying
>> data model is a (directed) graph.

That statement is premature. I'd like to leave it as it is.

>> Section 3.1
>> Here are examples of RDF triples <Example> The example above does
>> *not* constitute actual RDF syntax. Would find it better if the first
>> sentence would say so already and we get rid of the note afterwards.
>> Maybe something like "Triples allow us to express information such
>> as:" and then set the title of the example to "Information expressed
>> in the form of triples (pseudo-code, not actual RDF)" or something
>> like that.

Changed in the spirit suggested.

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

>>
>> The reference to SPARQL is probably to early here. I doubt a reader
>> will wonder how to query the data at this stage. I'd just remove it.
>> It's already included again later on.

The early reference to SPARQL was an explicit request from Gareth Adams 
from BBC. I like his rationale so prefer to leave it in.

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

>> Section 3.2
>> I don't think it's necessary to highlight the IRIs so much by marking
>> them as examples. Just add them to the text. Since they are blue and
>> underlined, they are visible enough. If you want them to stick out
>> even more, format them as <code> similar to how you did with
>> dbpedia.org at the end of that section.

I prefer to keep this style. I'll remove one example to make them less 
dominant.

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

>> Shouldn't "datatype" and "language tag" be definitions instead of just
>> being formatted in italic?

See above.

>> Does the note in that section really belong in the primer? I don't
>> care much but probably it should be removed. It's in RDF11-NEW.

Removed.

>> Section 3.4
>> ... without bothering to use an identifier. Hmm... think it would be
>> better to say *global* identifier because we have blank node
>> identifiers in concrete syntaxes.

Added.

>> "subject and object position" and similar things in previous sections
>> shouldn't be formatted like a definition. Just transform "subject" and
>> "object" to references, that suffices IMHO.

The notion that a bold-styled term is a definition is very much a 
"normative spec thing". Bold simply means here "strong", in the standard 
HTML fashion, and appropriate for this piece of information.

>> Section 3.5
>> "RDF provides a mechanism to group RDF statements in multiple graphs
>> and associate each graph with an IRI" -> ... and associate graphs with
>> an IRI (i.e., remove "each"; default graph) ??

Changed as suggested.

>> "Multiple graphs in an RDF document constitute an RDF dataset" -> "A
>> collection of multiple RDF graphs constitute an RDF dataset"

The current phrasing appears correct to me; saying "a collection of 
multiple.." might actually confuse people.

>> Why does "RDF dataset" link to Concepts whereas no other definition does?

The latter is not true. At the moment IRI, literal, datatype, blank node 
and dataset have links to Concepts. Maybe we should add a few more, time 
permitting.

>> For example, the statements in the first example -> in "Example 1"??

Changed as suggested.

>> I would suggest to somehow include http://example.org/bob in example 2

This would mean reworking all figures and examples. I see no strong 
reason to do this.

>> The IRI associated with the graph is called the "graph name" -> graph
>> name should be formatted as definition

See above.

>> Shall we really say that the graphs are *identified* with those IRIs??

I suggest not to reopen this discussion. I think the Note provides 
enough caveats.

>> Section 4
>> I would find it better to spell the variables like C, P etc out. So
>> Class, Property, Instance or <a class>. Overall I have to say though
>> that the table doesn't add much value and we wouldn't lose much by
>> just removing it.

The variables are explained clearly enough, I think, in the third 
column. I think the table has value and should be kept in.

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

>> List of vocabularies: Add Open Graph Protocol (http://ogp.me/),
>> millions more people will know it than Dublin Core and SKOS. Thus,
>> move schema.org and OGP to the beginning of that short list.

I prefer not to include OPG, as it is (or at least its documentation is) 
closely linked to one particular company.

>> "the more vocabulary ITIs are reused" -> s/ITIs/IRIs/
>> s/so-called netwrok effect/so-called network effect/

Corrected.

>> Section 5.1
>> Could we make the line numbers gray or something (I found the color
>> #999 works quite nicely in some of my other docs) to make it clearer
>> that these are not part of the syntax.

Done.

>> Section 5.1.2
>> "Turtle introduces a number of syntax shortcuts" -> syntactic shortcuts??
>> Really? "support for namespaces"? Support for namespace prefixes, right?

Corrected.

>> I would remove the subsection "Representation of blank nodes", doesn't
>> add much and isn't explained for the other syntaxes. You already say
>> that "This section gives by no means a full account of the Turtle
>> syntax".

Several people have argued in favor of this. On our todo list is to add 
a syntax example using the [] notation.

>> Section 5.1.3
>> "The two triples specified on lines 30-32 are not part of any named
>> graph" -> 27-29

Corrected.

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

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.

>> Section 5.2
>> "JSON-LD also provides a way to serialize RDF datasets through the use
>> of the @graph keyword." -> can be removed, this is already clear from
>> the very first sentence
>> "Each JSON object corresponds to an RDF resource" -> JSON object *in
>> the example above* (this is not generally true)
>> I don't really like the keyword aliasing in the example, but if you
>> alias it, please use "url" instead of "uri". Also, please include the
>> full absolute IRIs instead of bob#me, alice#me, and wd:Q12418. Rename
>> "born" to "birthdate", "friends" to "knows" and get rid of the array
>> (also for interest) and type-coerce "creator" to @id as well. So, in
>> the end, the example should look as follows
>>
>> 01    {
>> 02      "@context": "example-context.json",
>> 03      "url": "http://example.org/bob#me",
>> 04      "type": "Person",
>> 05      "birthdate": "1990-07-04",
>> 06      "knows": "http://example.org/alice#me",
>> 07      "interest": {
>> 08        "url": "http://www.wikidata.org/entity/Q12418",
>> 09        "title": "Mona Lisa",
>> 10        "subject_of":
>> "http://data.europeana.eu/item/04802/243FA8618938F4117025F17A8B813C5F9AA4D619",
>>
>> 11        "creator": "http://dbpedia.org/resource/Leonardo_da_Vinci"
>> 12      }
>> 13    }
>>
>> Unless someone thinks otherwise, I would prefer it this way though (to
>> make it more recognizable as JSON-LD and to show the why there's a
>> @type: @id in the context; keyword aliasing is really an advanced
>> feature IMO):
>>
>> 01    {
>> 02      "@context": "example-context.json",
>> 03      "@id": "http://example.org/bob#me",
>> 04      "@type": "Person",
>> 05      "birthdate": "1990-07-04",
>> 06      "knows": "http://example.org/alice#me",
>> 07      "interest": {
>> 08        "@id": "http://www.wikidata.org/entity/Q12418",
>> 09        "title": "Mona Lisa",
>> 10        "subject_of":
>> "http://data.europeana.eu/item/04802/243FA8618938F4117025F17A8B813C5F9AA4D619",
>>
>> 11        "creator": "http://dbpedia.org/resource/Leonardo_da_Vinci"
>> 12      }
>> 13    }
>>
>> "The @context key on line 2 points to a JSON document" -> to a
>> *JSON-LD context document*
>>
>> Since the context is so crucial for all of this, I think it is
>> important to include it directly in this section. It would also be
>> good to mention that it can be directly embedded into the document
>> instead.
>> Here's an optimized version of the context (without the keyword aliases)
>>
>> 01    {
>> 02      "@context": {
>> 03        "foaf": "http://xmlns.com/foaf/0.1/",
>> 04        "Person": "foaf:Person",
>> 05        "interest": "foaf:topic_interest",
>> 06        "knows": {
>> 07          "@id": "foaf:knows",
>> 08          "@type": "@id"
>> 09        },
>> 10        "birthdate": {
>> 11          "@id": "http://schema.org/birthDate",
>> 12          "@type": "http://www.w3.org/2001/XMLSchema#date"
>> 13        },
>> 14        "dcterms": "http://purl.org/dc/terms/",
>> 15        "title": "dcterms:title",
>> 16        "creator": "dcterms:creator",
>> 17        "subject_of": {
>> 18          "@reverse": "dcterms:subject",
>> 19          "@type": "@id"
>> 20        }
>> 21      }
>> 22    }

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.

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

>> Section 8
>> Could be remove completely IMO.

Disagree. Some sort of (short) conclusion is good practice in my book.

>> Appendix B
>> Could be removed as well or factored into Acknowledgements

Changed as suggested.

>> Appendix C
>> I don't really know what to do with this. Since most of the material
>> has been moved to section 5 it might make sense to move RDFa and
>> RDF/XML there as well. Or is there a specific reason why the have been
>> banned to the appendix? :-)

This was work in progress. Now done.

>> I think we can get rid of the JSON-LD
>> examples there. The JSON-LD spec explains this already (well-enough I
>> think).

To be discussed in a separate response.

>>
>> Finally, just as the figures, I think all examples should have a title.

Done.

>> I understand that these are a lot of changes and that we are running
>> out of time but I find it *very* important to make this document as
>> good as we can (it's quite good already btw.). If you need help, just
>> tell me. I'm more than happy to help editing the document.

Thanks a lot, that was very helpful indeed.

See the revised ED for changes [1].

Best,
Guus

[1] https://dvcs.w3.org/hg/rdf/raw-file/default/rdf-primer/index.html#

>> Thanks for the great work,
>> Markus
>>
>>
>> --
>> Markus Lanthaler
>> @markuslanthaler
>>
>>
>

Received on Wednesday, 19 February 2014 22:38:23 UTC