Re: [RDFa] RDFa primer review

Hi Ben,

I'm glad these comments were useful.
I have answered your answers below. Most of them are just acknowledging 
that what you are proposing as a fix (or postponing to future version) 
is OK.

Cheers,

Antoine

> 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!
>   
OK. Though I would have expected though bold to be more readable on B/W 
printing, which is still the strategy I have for reviewing docs ;-) Has 
W3C rules about that kind of thing?
>   
>> - [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.
>   
OK
>   
>> - [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.
>   
OK
>   
>> - "concept" (paragraph 2) sounds weird, especially for something like an 
>> event's date
>>     
>
> replaced with "field" which is explained immediately afterwards.
>   
OK

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

Yep.

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

I'll let people decide. I think it would be interesting to discuss this 
in the *Semantic Web* Deployment WG teleconf ;-)

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

Fair enough. If these details are presented somewhere, it's ok. Perhaps 
a link to the corresponding part of the syntax document would be useful, 
though.

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


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

You haven't done anything about this?

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

OK
>> - 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 same problem still occurs in 2.4! Sorry...
>   
>> - 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.
>   

OK!
>   
>> - " 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 :)
>   

I believe you ;-)

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

My point was that if it was possible for the fragment of the example to be
> <p instanceof="http://www.w3.org/2002/12/cal/ical#Vevent">
>     I'm holding
>     <span property="http://www.w3.org/2002/12/cal/ical#summary">
>       one last summer Barbecue,
>     </span>
then the author would not have any namespace problem due to her not 
controlling the complete XHTML document.
But if it's not possible to use full URIs of course this is less relevant.



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

My point here is that the current title of the section hints that it 
will actually explain how to create a vocabulary with RDFa. But I guess 
that the normal use of RDFa will not be to create ontologies (though 
it's technically possible).
 
>   
>> - 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.
>   
OK.
>   
>> - "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 :)
>   
OK.
>   
>> - 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.
>   
OK.
>   
>> - 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.)
>   
OK.
>   
>> ------- 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.
>   
Fair enough.
>   
>> ------- Sec 4
>>
>> - "W3C's standard" -> "W3C standard" ?
>>     
>
> fixed.
>   
OK!

Received on Sunday, 28 October 2007 22:05:13 UTC