Review of latest RDFa Core 1.1

Hi Shane,

This is a review of the following document:

http://www.w3.org/2010/02/rdfa/sources/rdfa-core/Overview-src.html

I did CTRL-ALT-SHIFT-S and did a diff-mark to view the differences. I am
only looking at text that changed, I haven't looked at the other text in
this review.

> 2. Syntax Overview 
> One important thing: In RDF it ... examples (and

Nitpicky - this sounds strange to me, strike "One important thing"? The
parenthetical statement is also complex - simplify the sentence via
something like:

"""
In RDF, it is common for authors to shorten vocabulary terms via
abbreviated URIs that use a 'prefix' and a 'reference'. This mechanism
is explained in detail in the section titled "Compact URIs". The
examples throughout this document assume that the following vocabulary
prefixes have been defined:
"""

> Fragments are commonly used in RDF vocabularies as a way of singling
> out a specific term in a document full of terms. However, you should
> be aware that while this is a common practice, the exact meaning of
> such URIs is not fully defined by the relevant internet standards
> (e.g., [  URI  ]). Work on this is ongoing.

Minor fix-up:

Fragments are commonly used in RDF documents as a way of singling out a
specific piece of structured data. While this approach is common
practice, you should be aware that the exact meaning of such URIs is not
fully defined by the relevant Internet standards (e.g., [URI]). There is
work that is currently being performed by the Internet standards
community to correct this oversight and a deeper explanation of this
approach is expected to be published in the near future.

> 4.2 RDFa Host Language Conformance
> The working group expects profiles..

"The Working Group expects default RDFa profiles to change ...."

> 4.3  XML+RDFa Document Conformance

Nice work, I love how simple this section is...

> CURIE vs. CURI

This has always bothered me, I know you don't want to change it, but I'd
like "CURIE" to be written out in the document as "Compact URI
Expression" not "Compact URI". At the moment, CURIE stands for "Compact
URI" -> what's the extra "E" for? Is it silent? I realize that this is
incredibly pedantic and bothers me more than it should.

> 7.5 Sequence

I'd love it if I could link to each step in the processing sequence. It
helps when explaining RDFa to people to be able to point them to the
exact section of the document that matters. I've found that when
discussing the processing sequence, this is incredibly difficult to do
and instead, I end up telling them go to Section 7.5, step #4 (or
something to that effect). It would be much nicer to just be able to
give them a link.

> 7.5 Sequence, Step #3
> Values in this attribute are evaluated from beginning to end (e.g.,
> left to right in typical documents).

I thought we settled on language that was not western-centric...
something like "in document order" or something else that makes sense
for traditional Japanese writing (top-down) or arabic (right-to-left).

> 7.6 Processor Status

I realize I wrote this section, but it's not as accurate as it should be:

ERROR should be replaced with rdfa:Error
WARNING should be replaced with rdfa:Warning

> 7.6.2  Processor Graph Terms

The dcterms:date property should include seconds.

"2010-06-30T13:40:23"^^xsd:dateTime

> Literal object resolution

This graph makes me feel like RDFa is very complicated in this respect
(resolving literals)... I know how we ended up here and don't think we
should change anything - just reflecting on where we are. Seeing the
complexity in visual form resonated with me. That said, it's good that
we have the graph there - it does simplify how one understands what is
going on.

> 9. RDFa Profiles
> from beginning to end, which each separate URI evaluated

Typo? "which" -> "with"

> the referenced profile is considered to be not recognized

Why is the word "recognized" in bold? I'm assuming because it means
something, but do we ever explain what "recognized" means to an RDFa
Processor?

> @@@@@ the use of the word resource above might be a problem @@@@@

Yes, it struck me as strange as well. How about:

"""
For every subject with a pair of predicates that have the values
"rdfa:prefix" and "rdfa:uri", create a key-value mapping from the
"rdfa:prefix" object literal (the key) to the rdfa:uri object literal
(the value).
"""

> B. The RDFa Vocabulary for Term and Prefix Assignments, and Processor
> Graph Reporting

Why not just call this section "The RDFa Vocabulary"?

> B.2  Processor Graph Reporting
> "The Vocabulary includes..."

It might be better to say "The RDFa Vocabulary includes...". I know it's
in section B.2, but it seems strange to capitalize Vocabulary but not
specify which vocabulary you're talking about.

> following term definitions

should probably say "the following triples"

> C.1 Major differences with RDFa Syntax 1.0
> RDFa 1.0 processor vs. am RDFa 1.1

Typo - "am" -> "an"

That's all I could find - the changes look good, thanks for making all
of them, Shane. :)

-- manu

-- 
Manu Sporny (skype: msporny, twitter: manusporny)
President/CEO - Digital Bazaar, Inc.
blog: Towards Universal Web Commerce
http://digitalbazaar.com/2011/01/31/web-commerce/

Received on Saturday, 5 March 2011 20:43:14 UTC