[RDFa] RDFa primer review

Hi,

Here is my review of RDFa primer, 18 Sept Editor's draft:
http://www.w3.org/2006/07/SWD/RDFa/primer/20070918/

On the general level, I find it very pleasant and useful document, and 
don't see any blocking major comment.

Yet there are numerous small things in my review: when doubting, I 
preferred to be picky and still write about my concern.
I hope this can prove useful, even if the schedule now seems tight...

Cheers,

Antoine

---------------

Coming from my previous review in January:
> - In the code examples, it would be really nice to emphasize (bold?) 
> the RDFa elements (that is, the xhtml tags and attributes) that are 
> introduced and explained by the current section (property, content, 
> rel,...), for pedagogical purposes

New comments:

------- Sec1:

- [minor] would it be worth mentioning some of the formulas devised in 
the "RDFa in 10 seconds" discussion? In the primer, I would expect to 
read that RDFa allows me to "create semantic markup" or "data markup", 
as a sexier complement to "transfer structured data between application 
and web sites [...] using extra XHTML attributes", which is the only 
explicit mission at this stage.

- [minor] is "extra attribute" on paragragh 2 (also at beginning of sec 
2.2) fully appropriate, while RDFa re-uses some already existing attributes?

- "concept" (paragraph 2) sounds weird, especially for something like an 
event's date

- on required reading: the RDFa primer can be read without being an 
expert in RDF, which is for sure a great thing. But the first time you 
mention RDF, you could point at the RDF primer, to offer curious reader 
with proper reference. The same is true for XHTML, especially since the 
reader is expected to be familiar with it.

- [minor] on the first occurrence of "URI" in paragraph 3: perhaps one 
or two sentences on the data model of RDF (which is also the one 
underlying RDFa), at least its being based on the notion of "resource", 
would be useful. Mentioning "Semantic Web" could also be fair. Currently 
this term does not appear in the main text at all: is it intended?

- on use of compact URIs (valid throughout the document). I think the 
primer should say something about the normative status of this proposal 
and the way it's used throughout the primer. Can we also use normal 
"full" URIs in RDFa?

- I would expect the reference to Dublin Core and others to come with 
references to readable material: for my browser, 
http://purl.org/dc/elements/1.1/ is dereferenced into the RDFS file, 
which is a bit tough ;-)


------- Sec 2.2:

- the example <p instanceof="cal:Vevent"> ... </p> could be made more 
precise, e.g. by keeping a part of its content. Otherwise it is not 
obvious which p tag the it is about...

- "isn't" should be "is not" to fit W3C writing rules (similar problems 
might occur elsewhere in the text, I'm not sure to have spotted them all)

- [minor] In the sentence starting with "Specifically, the start 
time...", something like an "also" between "be" and "represented" would 
enhance readibility.

- I don't know if this is important, but in the examples the line 
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML+RDFa 1.0//EN" 
"http://www.w3.org/MarkUp/DTD/xhtml-rdfa-1.dtd"> is not printed well (it 
does not split). There will be a similar problem on small screens.

------- Sec 2.3

- the first occurrences of @about and @rel read strange, a bit as if the 
reader had already been introduced to them before. I would use 
expressions like "for this, RDFa uses/introduces an XXX attribute"

- " For simplicity's sake [...]". Is introducing the proper vCard 
information in the example so complex? When reading the sentence I lost 
some time trying to figure out what the required information would look 
like. Not all readers are like me, of course, but still...

------- Sec 2.4

- "Fortunately, RDFa uses compact URIs[...]" This raises a problem 
related to the one I've mentioned for the introduction. Can one decide, 
to solve the problem of working with a fragment without loosing 
consistency, just to use full URIs for referring to the vocabulary 
elements? This is less beautiful to read, but should technically do the 
job...


------- Sec 3

- I find "creation of a custom vocabulary" confusing. It is formally not 
a capability of RDFa. The following section shows that one can re-use a 
custom vocabulary created with RDF, which is different.

------- Sec 3.1

- I don't really see the link between the two aspects of the section 
(compact URIs and custom vocabularies). Furthermore, compact URIs have 
been used since the beginning of the document, which does not make them 
a real "advanced concept" of RDFa

- "concepts are simply URIs". Again "concepts" alone reads weird. Should 
it be "classes and properties are simply URIs"?

------- Sec 3.2

- the example on @id would perhaps benefit from the reader's being 
explicitly reminded that @id indeed allows to refer to the concerned 
element as a web resource.

------- Sec 3.5

- I anticipate two problems with the example there:
-- The domain of foaf:img is foaf:Person. /user/markb should be used to 
denote Mark, and not Mark's profile (as it hinted at by the sentence 
"Shutr then notes that the profile photo isn't only Mark's profile photo").
-- foaf:img is a subproperty of foaf:depiction, which has foaf:depicts 
as inverse. Therefore, if we state (markb, foaf:img , photo.jpg) it 
follows from RDFS semantics that we also have (photo.jpg , foaf:depicts 
, markb ). That does not make the example useless (we could well have no 
RDFS reasoner available) but this makes it less convincing.

------- Sec 3.6

- the example is also not clear. If the navigable link is not usable, 
then why attaching the RDFa information to it? We could as well have:
<div about="/user/markb">
  <h1>Mark Birbeck's Photos</h1>
    <span rel="foaf:img" resource="/user/markb/profile_photo.jpg">
    <img src="/user/markb/profile_photo_thumbnail.jpg" />
  ...
</div>
It seems actually that a more important motivation comes from the 
possibly many situations where we would have no @href nor @src pointing 
to the resource (which includes the above case) or, as you point it in 
the same section, from the situations where the resource is not 
navigable at all.

------- Sec 4

- "W3C's standard" -> "W3C standard" ?

Received on Thursday, 18 October 2007 20:21:52 UTC