RE: [ALL] RDF/A Primer Version

This looks much better, and is really going to help sell RDF/A. My
comments are mostly tech writer oriented. 

General comments

While the use cases will make it much easier for readers to see the
benefits of RDF/A, the document has a very academic tone in places, with
a lot of "we this" and "we that" making it sound like it's a
presentation of research findings and not a primer, so I offered some
alternatives below.

Is Jo's last name lamda or lambda? Both come up a lot. Replace all
instances of one with the other.

A lot of the examples in pre elements have lines that are well over 80
characters, so they get cut off when printed.

I just noticed at least one change ("One immediately wonders" to "one
might wonder") from the 24 January draft that I printed out to read to
the one that's up on the 26th, so some of the things I reference may not
be the same any more.

I was trying to read this from the perspective of the Jos and Terris out
there as they wonder what's going on here and if it's worth the trouble.
With my tech writer hat on, I particularly watched for terms and syntax
that were used without being introduced.

section 1

Either say why it's called RDF/A or else change the name! Because it's a
method for storing RDF information in HTML primarily by using the "a"
hypertext linking anchor element? If you want to sell something, its
name should make some sense to the people you're selling it to. 

In the list in the first paragraph, you might mention microformats after
SVG. Nice trendy buzzword.

2.2

The paragraph beginning "One of Jo's friends" has single hyphens where
it should have em dashes, which do show up two paragraphs later ("Jo
then looks..."). This makes list-often and vocabulary-specifically look
like hyphenated terms.

"Jo then looks" paragraph: the discussion of properties and values in
the numbered list after this paragraph jumps up too many levels of
abstraction from the use case all at once, so this paragraph needs
something to ease the transition better, e.g. adding the following after
"within FOAF":

   She will add this information to her document as properties of that
document.

Or, something else that relates the concept of property values to Jo's
task.

I had to read the second half of numbered list item 1 too many times to
understand it. How about ending it like this:

  then the rel ("relationship") attribute can be added to the element
with the property name as its value.

I believe this is the first mention of the rel attribute, which is why
it should have the parenthetical expression after it. We want these
attribute names to have meaning to people, instead of being magic words.

2.2.3

The example document isn't as complete as the primer claims; it should
include the xmlns:foaf namespace declaration in the first tag. For that
matter, all examples that show the html start-tag should include the
xmlns="http://www.w3.org/1999/xhtml" attribute setting as well, because
a key reason to use XHTML instead of HTML is to allow the kind of
automated use of documents that Jo Lambda is laying the groundwork for
with the markup she's adding.

2.3

After the first example but before the line "The title of the group..."
add this: 

  Square brackets enclose "foaf:Group" because it's a special form of a
URI called a CURIE, which is covered in more detail in section 4.4 of
this document.

Don't just throw in new syntax and hope the reader won't notice! Also,
shouldn't the "G" in "foaf:Group" be in lower case? If not, explain why
in the document.

Last paragraph of 2.3 after "and not to the individual member of the
group" I had written in "why" there, but later wrote in this as
something to add: "for reasons we'll see in section 4.2." (If you don't
want to refer to specific sections as a style thing and just say "later
in this document" instead, that's fine, but it's good to reassure the
readers that the obvious questions that crop up in their minds as they
read will be addressed at some point.)

Add to very end of paragraph after "to be set to foaf:member":

  by entering this in square braces as the link element's href value.

It would be nice to add a section 2.4 that sums up what Jo's done and
mentions her clicking a button on some "update departmental information"
page to kicks off a script to harvest the information she's added to her
pages so that the intranet departmental address book, etc. all get
updated. It would be a nice finish to the scenario by showing the data
being put to a good use that anyone can understand.

3.1

Third paragraph: "We'll show" instead of "We explore."

Fourth paragraph: "We consider literal properties first and the URI
properties second." How about

  We'll look at two kinds of properties that we can add: literal
properties and URI properties.

3.2

After

   An RDF/A-aware browser would thus extract the following RDF triples

add

   , expressed here in N3 notation:

eighth paragraph: drop ", at this point in the presentation, "

4. Very nice intro.

4.2  Tie this in with the about="#andrew" issue from section 2.3.

"One might now wonder..." Don't even mention bnodes if you're not going
to say something about what they are. (The RDF Primer doesn't mention
them.) This paragraph could say something like this:

  It is possible for meta and link elements to describe parent elements
that have no name identified in an id or about attribute, but this
requires the use of more advanced RDF syntax.

4.4 

Change

    We now address URI duplication, RDF/A's most significant data
duplication issue, with Compact URIs, known as CURIEs.

to something like

  Compact URIs, known as CURIEs, ease the URI duplication problem we've
seen in the above examples, making data more compact.

Again, I think this primer has taken a great step toward becoming
something that will convince people of the value of RDF/A in particular
and RDF in general.

Bob
http://www.snee.com/bobdc.blog

Received on Friday, 27 January 2006 15:56:38 UTC