Re: [RDFa] RDFa primer review

Antoine,

Thanks for your very useful comments. Here is how I've addressed them.
All changes have been committed (and will soon be snapshot after I check
the pubrules.)

-Ben

=============


> Coming from my previous review in January:
>> - In the code examples, it would be really nice to emphasize (bold?) 
>> the RDFa elements

A much requested enhancement, now done!

> - [minor] would it be worth mentioning some of the formulas devised in 
> the "RDFa in 10 seconds" discussion?

I'm leaving that for the next and final draft, as this requires a bit of
marketing think.

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

fixed.

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

replaced with "field" which is explained immediately afterwards.

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

Added a pointer to the RDF Primer. I think there are sufficient pointers
to XHTML as is.

> - [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?

We've tried to stay away from too much RDF stuff at this stage, which is
also why we're not using the term "Semantic Web." Unless more folks feel
strongly about this, I'd rather stick to the current approach of minimal
RDF details.

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

CURIEs are explained in detail in the RDFa Syntax document... my take is
that the Primer shouldn't deal with normative/non-normative discussions,
it should just show people how to do RDFa. Thoughts?

In the places where you see CURIEs used in the Primer, you *cannot* use
full URIs. Only in @resource can you use either, where a CURIE is then
wrapped in []. But we held that use case off from the Primer, since it's
not a first-pass issue.

> - 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 ;-)

fixed.

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

fixed.

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

fixed the sentence to make it clearer.

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

fixed.

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

I've tweaked the language regarding @about.

@rel already exists in HTML, so it does in fact exist already.

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

We tried doing it the right way, and yes it does get overly complicated :)

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

I'm not sure I understand this comment.

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

True, but for the reader that doesn't know RDF, it seems simpler... the
introduction states clearly that all of this power derives from RDF.

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

yes, this was a bit of a dumping ground for a few small issues I needed
to explain more thoroughly.... will try for next WD to do better.

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

Trying to steer clear of too much RDF terminology. The word "concept"
seems to be okay with other readers, I'd like to keep it for this round
and see what the feedback is. But your point is noted :)

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

added some clarification.

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

Yes, this is the usual issue with introducing novices to the
non-information resource problem.

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

Good point. For the next version, I'll try to come up with a better
example, though there is actually some value to a really simple example
(that might already be implied by a RDFS reasoner.)

> ------- Sec 3.6
> 
> - the example is also not clear. If the navigable link is not usable, 
> then why attaching the RDFa information to it?

For the same reason we have @content: because there is a
human-meaningful resource, and a machine-meaningful resource that's not
quite the same. Co-locating them helps users "find" the metadata
correctly when using augmented browsers.

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

fixed.

-Ben

Received on Friday, 26 October 2007 05:41:52 UTC