Re: RDFa Primer ready for Working Group review

Hi Ben,

This is a review of the Apr 22 Editor's Draft of the RDFa Primer. Note
that I've exchanged points of view with my colleague Carlos Tejo, and
some of the comments are his.

General comment:
****************

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.

Specific comments:
******************

* 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. Many web
browsers are integrated with the address book. For many users, adding a
new contact is usually as easy as right-clicking with the mouse.

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

  b) Which level of expertise on HTML is required? This document is
targeted to people with (basic) knowledge of HTML, and that's a subset
of the people who publish content on the web. The previous paragraph
implicitly restricts the target audience to HTML authors ("RDFa allows
HTML authors to [...]"), but I suggest to make that explicit.

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

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

* The second example of Sect 2.3. The outer <div> contains
@class="blog-entry", but I cannot find a good reason for this attribute.
Unfortunately, I think it may create confusion (@class is no longer a
RDFa attribute, isn't it? :) I suggest to drop this attribute.

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

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

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

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

Congratulations to the editors for the document. All the best,

El mar, 22-04-2008 a las 03:10 -0700, Ben Adida escribió:
> Hi all,
> 
> As promised, here is the RDFa Primer, ready for Working Group review, as 
> per our Task Force vote last Thursday.
> 
> http://www.w3.org/2006/07/SWD/RDFa/primer/20080422/
> 
> This is a *significant* rewrite of the Primer. It is shorter and 
> contains less RDF. At the same time, we believe it is significantly 
> easier to read for HTML authors, our main target, without compromising 
> on the benefits of RDF.
> 
> Unfortunately, as I am in Beijing, I won't be able to attend the call, 
> but I, like the rest of the task force, look forward to your comments!
> 
> -Ben

-- 
Diego Berrueta
R&D Department  -  CTIC Foundation
E-mail: diego.berrueta@fundacionctic.org
Phone: +34 984 29 12 12
Parque Científico Tecnológico Gijón-Asturias-Spain
www.fundacionctic.org

Received on Wednesday, 30 April 2008 16:11:56 UTC