feedback on RDFa primer

I could suggest a lot of wordsmithing things (places to convert passive
voice to active, etc.) but will hold off on that until someone tells me
that that the Primer has reached a stage where that would be the most
useful.

Four overall comments:

- There's too much emphasis on browser RDFa awareness as the reason for
adding markup. This can lead to an XLink-like chicken/egg situation of
markup usage and browser support waiting forever for the other to move
forward. (Note that with XLink, everyone's given up on waiting.) Part of
the point of RDFa is that it's easy to write applications, so it would be
good for the primer to mention other potential applications--perhaps Jo's
friend Jack might have a script that he wrote to check his friends'
information pages and update his own address book based on what it found.

- I don't like the use of the term "field". I assume it's intended as a
user-friendly term for a unit of information, but it means so many things
in so many contexts (e.g. a database field, a form field) that when used
among these terms that have very specific meanings in a document addressed
to beginners it can be confusing. This can be addressed by a sentence or
two before the first use of the term explaining that, for the purposes of
the primer, it refers to a piece of labeled data or metadata.

- Similarly, the term "declare" is often used in a sense much different
from its traditional IT uses. An informal tone is good for a primer, but
loose usage of technical terms is not the way to achieve this. A possible
revision of one would be to replace "@property on span declares the data
field cal:summary" to @propery identifies the span element's contents as a
cal:summary".

- I'm a firm believer in bolding key parts of code samples, and it would
be particularly useful in a primer explaining to the reader about new
markup that they can add to existing markup that they're already familiar
with.


The rest of this is mostly suggestions for phrases and sentences to add
for clarity.


Section 1, change this

  Where the data is already present on the page, e.g. a photo caption, the
author need not repeat it.

to

  When data such as a photo caption is already present on the page for
human readers, the author need not repeat it for automated processes to
read it.


Replace the phrase

  in a machine-parsable way, the standard iCal format: 20070916T1600-0500
(which is clearly not pleasant for human display)

with

  in a machine-parsable way: 20070916T1600-0500, the standard ISO 8601
format used by iCal (which is cumbersome for human readers)


Replace

    is ignored by the RDFa portion of the browser: it has been replaced by
the explicit @content.

with

   is ignored by processes parsing for RDFa data, which instead reads from
the  the explicit @content.


After the sentence beginning "Jo discovers the vCard RDF vocabulary..."
add a sentence about what vCard is to give some context to why Jo chooses
to use it. (The next paragraph uses the term "vcard" as a noun, and as
readers we have no idea what a vcard is.)


Change

  @about is inherited from parent elements in the XHTML: the value of the
@about on the nearest containing element applies.

to

  The @about value is inherited from the nearest ancestor with this
attribute set: the parent element.


Change

  The only places where this doesn't happen is when @content overrides the
element's content, which is inevitable when human and machine
readability are at odds.

to

  The only places where this doesn't happen is when @content  overrides
the value displayed in the element's content, in which case the @content
value must be updated along with the displayed value.


Change

  which makes it particularly difficult to add the vocabularies in the
html element at the top of her page

to

   which makes it particularly difficult to add the namespace declarations
 in the html start-tag at the top of her page

(The html element isn't at the top of the page; it's the document element!)


Change

  We can use the convenient inheritance of @about to refer to the photo
once, and add as many fields as we need:

to

  We can use the convenient inheritance of the @about value to name the
photo once and then add as much metadata as we want for that photo
between the start- and end-tags of the element with the @about value:



In 3.4, in "The simplest way to mark this up without attempting to resolve
unique identities for photo subjects", I'm not sure what it means by
"resolve".


In section 3.5, after "except the direction of the relationship is
reversed:" add

  (that is, while @rel tells us that /user/markb has a foaf:img at
/user/markb/profile_photo.jpg, @rev tells us that
/user/markb/profile_photo.jpg depicts /usr/markb)

(This idea is not particularly clear from the way that section 3.5
presents it.)


Section 4 starts off as an introduction to RDF for people who don't know
what it's about and by the third and fourth paragraph is using vocabulary
that would only make sense to readers who already understand RDF. I would
change the term "literals" to "literal string values" in the third
paragraph and add something like this before the fourth paragraph:

    A collection of triples is often called a graph because when the same
URIs appear as the subjects and objects of multiple triples, the
triples can be treated as a collective unit that is greater than the
sum of its parts. (While it is not unusual to have a program create a
visual representation of one of these graphs, it's actually named
after the computer science data structure graph, not the visual
presentation of one.)

Then change

  All subjects and predicates are nodes, while objects can be nodes or
literals.

to

  All subjects and predicates are nodes of such a graph, while objects can
be nodes or literal string values.


After the n3 code in 4.1 and 4.2, it would be good to add plain English
restatements of the n3 triples. After that, readers should be able to
figure it out the rest for themselves based on the pattern, but the blank
node of 4.1 makes this a bit tricky for beginners.


In "the camera it was taken with in corresponds to the following triple"
take out "in".


Bob DuCharme

Received on Monday, 24 September 2007 16:51:53 UTC