Re: RDFa Primer ready for Working Group review

Hi Diego,

Thanks for your comments on the Primer! Here's how I've addressed your 
points.

> The document is clear and concise. It is very evident that a great
> effort has been made to simplify the previous version. By removing the
> RDF snippets, the document may annoy advanced users, but it is more
> accessible for novice users. However, I don't have a strong opinion on
> which version (the current one or the previous one) is better. I think
> the previous one was more complete and didactic, and the current one is
> easier to follow. The old one is more useful as a tutorial, and the new
> one looks like an article. Both of them are interesting, but I don't
> have any particular suggestion on how to merge them.

We are definitely targeting HTML authors first with this Primer. We 
decided we couldn't target both HTML and RDF communities in one 
document, and we felt the higher priority was HTML authors (RDF authors 
tend to be aware of RDFa already.)

> * Sect 1: "an author's email address [could be easily copied] to the
> user's address book". It is difficult to see the value of this.

changed to "complete contact information," where it's more than just an 
email address.

> * Sect 1, last paragraph: "Readers of this document are not expected to
> understand or even know anything about RDF". Two questions here:
> 
>   a) I know this may be controversial, but in my opinion, a productive
> user of RDFa must know the essentials of RDF.

True, but those essentials can be learned via the RDFa path, not 
necessarily by grabbing the RDF specs directly. We're hoping RDFa will 
introduce folks to RDF via a different route.

> Although I agree with the
> quoted sentence, we should stress that it applies to the "readers of
> this document", and not to the "users of RDFa".

I specifically worded it this way to stay uncontroversial.

>   b) Which level of expertise on HTML is required? This document is
> targeted to people with (basic) knowledge of HTML,

Correct. Added a line to that effect.

> * Some links to the references section are missing. In particular, the
> term "Creative Commons" (Sect 2.1), "Dublin Core" (Sect 2.2),
> "FOAF" (Sect 3.1) and "RDF" (Sect 4) should be linked to the references
> at the bottom of the document.

Done.

> * The last paragraphs of Sect 2.2 describe CURIEs. The explanations may
> be a bit over-simplified. In particular, I don't like the notion of
> "importing" concepts and "importing" the DC vocabulary. This language
> may be familiar for Java developers, but it may introduce confusion for
> HTML authors.

So far, the feedback from HTML-oriented readers has been positive. Do 
you have a specific example of someone confused by this? We've worked on 
this language quite a bit, so I'd rather not change it unless we have 
significant evidence that readers are confused.

> * The second example of Sect 2.3. The outer <div> contains
> @class="blog-entry",

removed.

> * Another comment regarding the same example. The paragraph says that
> the "diagram [...] represents the underlying data", but actually it only
> represents *part of* the triples that can be extracted from the markup
> (precisely, the triples that are extracted from the highlighted part of
> the example). I suggest to draw the complete graph.

I added a few words to explain that I'm representing the new markup only.

> * Sect 4. The acronym "aka" is used. This slang is not obvious for
> non-native speakers. Please rewrite the sentence (or use <acronym>).

removed.

> * Sect 7 (Bibliography). Many references are not cited in the text, and
> should be removed: ICAL-RDF, VCARD-RDF, XSD, XSD-DT.

done.

> * It think it is not complete clear for the novice reader when to use
> @property and when to use @rev. Unfortunately it is difficult to explain
> this without explaning the two kinds of properties in RDF. If we want to
> keep the document as simple as possible, we can just say the @rev must
> be used when associated to a URL.

In 2.2, I added a few words at the introduction of @property that should 
make this clearer.

Thanks again!

-Ben

Received on Monday, 26 May 2008 18:39:19 UTC