Notes on the 2002-4-26 Working Draft of RDF Primer

Overall it's very good, and there are a lot of bad explanations of RDF in the world, so it's needed. Of the parts labeled "@@" listing new material to be added, I think some of those anticipated parts are too ambitious--in othe words, they will require enough work that it's not worth holding up the progress of this much-needed document. For something like the section on reification, I would add a paragraph or two as soon as possible instead of waiting until there's time to write two pages. 

To respond to some earlier comments about the Primer at http://lists.w3.org/Archives/Public/www-rdf-comments/2002AprJun/0176.html, I wanted to mention that describing the purpose of all the other RDF W3C documents is very valuable. Someone who wants to learn about RDF and goes to www.w3.org/TR is going to be overwhelmed by all the RDF documents there, and will likely gravitate toward the Primer. For this reason, the Primer is a fine place to summarize the purpose of the other documents. I think that the Primer is well-positioned for a technical audience. 

thanks,

Bob DuCharme          www.snee.com/bob           <bob@  
snee.com>  "The elements be kind to thee, and make thy
spirits all of comfort!" Anthony and Cleopatra, III ii

~~~~~~~~~~~~~~~~~~~~~~~~~~~~

One general content comment: I would mention N3. It's simple, and good for RDF beginners. Much RDF literature asserts that RDF isn't just an XML application, and then it explains what elements and attributes are as if there are people interested in RDF who don't know the first thing about XML--really, how many are there? I'm sure there are plenty of people quite comfortable with XML who are intimidated by the verbosity of RDF in XML and all those URIs, and N3 is a great way to show them the basic concepts in a concise way. In fact, it's fun. The primer could use eight or nine paragraphs about N3 and then a pointer to Tim Berners-Lee's primer.

General proofreading comments: 

The XML Rec, like the SGML standard before it, hyphenates all use of the terms start-tag and end-tag.

em dashes should be two hyphens (--), not one (for example, "a simple structure - a list of 'triples'") throughout.

e.g. and etc. are overused. Instead of e.g., just say it in English: "for example". A lot of "etc." can be removed by changing something of the form "x, y, z, etc." to "such as x, y, and z", which makes it clear that x, y, and z are examples and not a complete list.

Parentheses are used so much throughout the document that reworking many of the sentences to remove the need for the parentheses would help the document to flow better. I pointed out some of the obvious ones below.

Specific comments:

(Some of these are general, some are just suggested wordsmithing.)

Section 1. Introduction

(also in abstract) The abstract and the first paragraph of the Introduction
already seem a bit dated by describing the value of RDF almost completely in
terms of use on the Web to describe resources on the Web. There is the
qualifying statement ("However, by generalizing the concept..."), but I think
this doesn't convey the value that more and more people are getting
from RDF in applications unrelated to the Web. Ironically, I liked the
introductory language on the value of RDF in 6.1 more when it's shown within
an example (search for "third example") of a magazine article incorporating
Dublin Core terms.


"small chunk of RDF in its XML serialization format" As a Primer, this should briefly explain what it means by "XML serialization format."


"definitive or fully-complete answers" change to "definitive or complete answers"


2. Making Statements about Resources


'(note the use of "August 16, 1999" to identify a date).' Why? 


2.1 

"URIs are similar to URLs" because URLs are a kind of URI, this is like saying that dogs are similar to dalmatians. The relationship should be made clearer. 


2.2 

The sentence beginning "By qualifying tag names with the URIs of their namespaces" introduces an example but the example doesn't demonstrate the technique being introduced--it doesn't qualify tags with the URIs of their namespaces, but instead declares and uses namespace prefixes. To remedy this, add a sentence like this after "as the URI for the namespace," which takes care of the "@@" comment following it:

Instead of actually adding the full URI to each start-tag, it's more convenient to declare a prefix that indicates the use of a particular URI and to then use that prefix to show that an element or attribute comes from that namespace. In the following example, xmlns:my="http://example.org/xml/documents" declares the prefix "my" for the namespace http://example.org/xml/documents, and the prefix of "my:" shows which elements come from that namespace. See the "Namespaces in XML" Recommendation for more information. 

Also, right after the example, change "Since everyone's tags have their own URIs" to "Since everyone's tags can have their own URIs". (Many of my tags do not have their own URIs, but could.)


2.3

If the graphs were created by a free program, it would be nice to point out to beginners what the program was when the first graph is shown, or some other program that they can use themselves.


"...since we have a URI for the creator of the page, it is a full-fledged resource" as opposed to non-full-fledged resources? How about this instead: "since we have a URI for the creator of the page, we can name this same resource as the subject or object of as many RDF statements as we like".


"Using URIs to identify properties" Start a new paragraph with that sentence.


'e.g. "John Smith"' The e.g. is unnecessary because of the "in our example" in the beginning of the sentence. 


"distinct properties involved (even if a program can't automatically determine the distinct meanings)." 

  change to  

"distinct properties involved, even if a program can't automatically determine the distinct meanings.


"For example, a user could search the web..."

  to flesh this out the reasoning a bit better, change to 

"If different book reviews on the web conformed to different DTDs, consistent use of RDF resources, predicates, and objects in them would let a user search the web..."

That should cover the "@@" comment right after it. 


Change the sentence beginning "and information in these formats" to begin "Information in these formats". In most tech writing, when the sentence introducing the bulleted list ends with a colon ("such as:"), a new sentence gets started after the list. Also, for consistency, the items in the list should either all end with periods or all not end in periods.


"However, suppose we wanted to record the month, day, and year as separate pieces of information? Or, in the case of John Smith's personal information, suppose we wanted to record his address." Either convert the first sentence's question mark to a period or the second sentence's period a to question mark. 


(shortly after that) change "However, suppose we wanted" to "However, what if we wanted" (because "suppose" has been used twice very recently)


"The unlabeled node, or blank node" Has "blank node" replaced the term "anonymous node", or are they qualitatively different? Either way, something should be mentioned here to set it straight in the novice's mind, because a lot of RDF literature talks about anonymous nodes. 


3.


"These edges can also be described as triples of subject node , at the blunt end of the arrow/arc, property arc and an object node at the sharp end of the arrow/arc." 

  change to 

"These edges can also be described as triples consisting of a subject node at the start of the arrow that represents the arc, the property arc, and the object to which the arrow points".

(On the other hand, I always thought that the graph edges corresponded to the arcs and did not included the nodes that the edges connect.)


"The property arc is interpreted as an attribute, relationship or predicate of the resource, with a value given by the object node content." Insert the word "subject" before the word "resource" for clarity, because a triple can have two resources: the subject and object.


"namespace-qualified elements and attributes names" remove "s" from "attributes"


"The (namespace URI, local name) pair are chosen such that concatenating them forms the original node URI."

  change to 

"The name created by appending the local name to the namespace URI forms the original node URI."



"The nodes labeled by string literals (which are always object nodes) become element text content or attribute values."

  change to 

"The nodes labeled by string literals, which are always object nodes, become element text content or attribute values."


In all the examples, don't bother with the XML declaration. If a document is in UTF-8 or UTF-16, the XML declaration is nearly always unnecessary. It just makes the document non-embeddable into another document (which is something that would be handy with RDF!), and it makes the examples that much less concise.


"Following the rdf:RDF on this same line is an XML namespace declaration"

  change to

"On the same line, the rdf:RDF start-tag has an XML namespace declaration"


"Line 3 specifies another XML namespace declaration, this time for the prefix ex:. This is expressed as another xmlns attribute of the rdf:RDF  element, and specifies that the namespace name..."

  change to 

"The rdf:RDF start-tag's second attribute, on line 3, associates the namespace name..."


'The ">" at the end of line 3 indicates the end of the rdf:RDF start-tag.'

Just delete the sentence. Assume a basic knowledge of XML, even if it means pointing to a basic introduction somewhere. Trying to explain RDF and XML at the same time will only confuse people; look how confused people who already know XML are by most RDF introductions.


"appending creation-date to it" change to "appending the element name creation-date to it" to make it clear that the creation-date value is not what is being appended.


"the new namespace prefix dc: we defined in Line 3." Replace "defined" with "declared".


Paragraph beginning "This is similar to our previous examples" is really good. 


'However, it uses an attribute rdf:parseType="Resource to indicate' (closing double quote needed)


"(known as striping)" change to "(known as striping because of the alternation of node elements and property elements in the XML representation)" You could even point to http://www.w3.org/2001/10/stripes/--in fact, I would consider adding that entire document to the Primer.


4.

After the second paragraph, describe a little about why it's worth going to the trouble to create a schema. What value does it add? Mention a free validator.


4.2

"A property may have zero, one, or more than one range property."

  change to 

"A property may have zero or more range properties."



"are defined elsewhere>" delete ">"



"A property may be a specialization of zero, one or more properties."

  change to 

"A property may be a specialization of zero or more properties."



6.2

"because of its abilities for dealing with"

  change to 

"because of its ability to deal with"


"First says that the image can't be used" 

  change to 

"The first says that the image can't be used"


6.3

"XPackage applications include specifying the stylesheets used by a document, declaring the images shared by multiple documents, indicating the author and other metadata of a document, describing how namespaces are used by XML resources, and providing a manifest for bundling resources into a single archive file."

  change to 

"XPackage applications can specify the stylesheets used by a document, declare the images shared by multiple documents, indicate the author and other metadataattributes of a document, describe how namespaces are used by XML resources, and provide a manifest for bundling resources into a single archive file."



"Resources (such as the XHTML document, stylesheets, and images) are described"

  change to 

"Resources, such as the XHTML document, stylesheets, and images, are described"



6.4

The intelligent routing section really reads like a first draft and has some catching up to do with the rest of the document before it's ready for public inclusion.


7.3

At least insert a paragraph or two defining reification.


8. 

The proposed "RDF as Data Model" section looks pretty ambitious. I would drop it for now instead of letting all the work that this section would require hold up the progress of the entire Primer.

Received on Monday, 16 September 2002 17:04:34 UTC