ISSUE-71: DRAFT Last Call response to Shelley Powers


Shane - pay particular attention to this e-mail because I suggest that
we make editorial changes to the text in the RDFa Core specification.

This is a draft response to Shelley Powers' Last Call comments on RDFa

On 01/03/2011 10:40 AM, Shelley Powers wrote:
> First, I want to say what an amazingly clear and easy document to
> follow. I have never written an RDFa processor, but actually feel I
> could from the instructions--and have a high degree of confidence that
> the result would be both accurate and consistent. Since I've never
> written an RDFa processor, and the thought of doing so in the past
> intimidated the heck out of me, this says a lot about the quality of
> work in the spec.

Thanks Shelley - much of the credit goes to the editor of the
specification - Shane McCarron, and the large number of reviewers that
have helped clarify the document over the past several years.

> I really like @profile, though I know it caused some very valid concerns
> at one point. However, you did address the concerns in the document. The
> only thing I would suggest is ensuring that RDFa authors are aware of
> the potential problems with profiles and the use of scripting to perform
> RDFa processing. But since the author controls both (the use of the
> script and the use of profile), they do control the solution.

We'll add something to the effect of these two paragraphs to section 9:
RDFa Profile:

"Web authors utilizing RDFa Profiles should be aware that if a profile
that they list is not available for any reason, and the RDFa Processor
has not previously cached the profile, that all triples that should be
generated as a result of the profile will not be generated. In addition,
any other triples that exist in a subtree of the DOM will not be
generated either since processing halts for a subtree in the DOM when a
@profile cannot be fetched."

"Web authors utilizing both RDFa Profiles and a JavaScript-based RDFa
processor should be aware that same-origin security protections are
enforced for RDFa processors, just like any other JavaScript code. This
means that if a @profile is not served up using CORS or a similar
technology that the processor may fail to retrieve the profile and thus
the expected triples in the subtree of the DOM where the @profile is
specified will not be generated."

> The only remarks I have are more about the readability of the document.
> As such, they are more suggestions rather than specific requests. The
> only item would strongly advise you to consider is bringing in an
> accessibility expert, because of the frequent use of visual cues.

Shane is a member of the Protocols and Formats Working Group (PFWG) and
has some experience with accessibility concerns. I believe that we had
asked the PFWG to review the RDFa Core specification, but had not had a
review by that group as of yet. There is still time to comment on
accessibility issues in the document, as styling of the document is an
editorial change and can be made before the specification goes to
Recommendation status at the W3C. We do our best to follow all
publishing guidelines provided by the W3C, which include a number of
accessibility checks that must be passed during the publication process.

> RDFa review
> In Section 2.2 Examples, you mention the link and meta elements, but in
> the section following you reference them as a "concept" but the concept
> was never explained. The transition was confusingly abrupt. Especially
> going right into CURIEs.
> In the following example, you use a CURIE, but again the transition is
> lost because of the brevity of the explanation leading into the example.

Yes, the transition is abrupt and we don't explain the "concept" behind
the link and meta elements. Something as simple as:

"In HTML, authors can include metadata and relationships concerning the
current document by using the link and meta elements. For example, the
author of the page along with the pages preceding and following the
current page can be expressed using the link and meta elements:"

We also don't explain why CURIEs are important, we should have an
example with full URIs first, and then explain that those URIs could be
compressed using CURIEs.

> I'm also a little concerned about the use of color highlighting. From an
> accessibility stand point you may want to also make the text bold. In
> addition, though I don't know if you want to be this verbose, you may
> want to include a reference to the item of importance in the example, so
> that those using a screen reader aren't left to guess what's important
> in the example.
> For instance, instead of the following sentence:
> In many cases a block of markup will contain a number of properties that
> relate to the same item; it's possible with RDFa to indicate the type of
> that item...
> Use:
> In many cases, a block of markup contains a number of properties that
> relate to the same item. You can use the RDFa typeof attribute to
> indicate the type of that item...

We'll keep the text color highlighted, and implement your suggestion.
Before each example in section 2.2, we will have a one sentence
description about the significance of the markup in the example.

> The examples also reference terms that are defined later in the
> document, such as using triples. For your audience, I don't know if you
> need to ensure clarify to a newcomer to RDF, but you might want to
> provide a brief explanation, just to ensure that a person doesn't get lost.

At the very least, we will link from each mention of "triple" to the
definition of what a triple is in the RDF Terminology section.

Previous comments suggested that we start the document out with a number
of examples. I would suggest that we move the examples to after the RDF
Terminology section, but this would conflict with a decision that was made

I have combed section 2.2 for any other RDF-specific terminology and we
should link to explanations of the following words:

* vocabularies
* compact URI (CURIE)
* RDFa Profile Document
* prefixes
* terms

> In the conformance section, you mention about authors needing to ensure
> they remove unnecessary white space, but I'm not sure the authors are
> going to see this section. Perhaps an example earlier? Just to ensure
> all audience members see this critical information?

We will add the following example in that section to ensure that an
example of unnecessary whitespace is provided. For example, try to not
do this:

My name is <span property="foaf:name"> John Doe   \n  </span>

but do this instead:

My name is <span property="foaf:name">John Doe</span>

> In section 6.1, I realize that this section is targeted at the person
> asking, "Why not QNames?", but others could benefit from the discussion.
> To ensure everyone has the same background entering the section, perhaps
> a brief explanation of what is a QName?

We will add an opening paragraph explaining the historical significance
of QNames and what they were used for when they were created for XML.
Something to the effect that Section 3 has in this document describing

> The Chaining section was excellent. The only thing I would say about the
> examples is that the spans would most likely contain actual visible
> text, though that data isn't of matter to the person or people writing
> the processor. This is covered in the earlier examples, but redundancy
> can't hurt.

Yes, in fact all of the examples in that section would be more realistic
if we added text referring to Albert Einstein, the German Empire and the
United States. We will make those changes.

Thank you for reviewing the specification, Shelley, we will make the
changes listed above and ensure that we try to find someone well-versed
in accessibility to review the specification for any accessibility concerns.

Since this is an official response from the RDFa Working Group, could
you please review the changes that we plan to make and let us know if
these address the concerns that you raised.

-- manu

Manu Sporny (skype: msporny, twitter: manusporny)
President/CEO - Digital Bazaar, Inc.
blog: Linked Data in JSON

Received on Sunday, 23 January 2011 22:53:33 UTC