RDFa Primer review

Review of RDFa Primer, as read by an entry-level web developer.

General Readability
-------------------

Here some stats on the writing to help get an idea of where some of the
high-level comments came from:

http://www.readability.info/index.cgi?u=http://www.w3.org/2006/07/SWD/RDFa/primer/

Check out some of the readability stats - 11.4 for a Fog Index and 10.4
for a SMOG-Grading (US reading grade level) is a bit on the high side
for a document that is supposed to be a primer.

The syntax document is about 1 grade level higher than the primer...
just something to consider:

http://www.readability.info/index.cgi?u=http://www.w3.org/TR/rdfa-syntax/

Compare this with the press briefings that the US Whitehouse releases
(stop snickering up there in the peanut gallery!) - I'm using this as an
example of lowering the reading level (and thus understandability) even
though the information conveyed is rather complex:

http://www.readability.info/index.cgi?u=http://www.whitehouse.gov/news/releases/2008/03/20080306-3.html

Fog Index of 9.8, SMOG of 9.5. Just meant as another evaluation tool and
by no means a final method of determining readability.

Text Markup
-----------

We mention several elements in the prose, but don't use a different
typeface to make them stand out. It is difficult to scan a sentence and
know which are elements - they look like mis-edits or errors in the
prose. For example:

"Jo then sets up her vCard using RDFa, by deciding that the p will be
the container for her vcard."

Not only does that sentence make me chuckle every time I read it - I
thought it was a mis-spelling and had to scan the sentence three times
to understand what it was saying. We should say "the P element" and
bold/+1 size/courier the font.

URLs that are mentioned in prose should get the same treatment.

Denoting Triples
----------------

Any triple blocks that we have in the document should use the same
background color as the one that is used in the RDFa Syntax Document -
#F0E68C.

Section 1:
----------

Editorial issues:

[RDFa Use Cases] - no link/reference.

Words/concepts that were scary in Section 1:

XML Schema Definitions - what are those and why do I need to know about
them?

General input:

It feels as if the first section, at the very beginning needs to say
something to this effect:

"Look, Mr./Ms. Web Developer we're only just scratching the surface of
what the web can do. The web is about communication, and we're not using
it to its full potential. Think of the web today like watching a movie
with the sound turned off. There is dialogue and certain audio cues that
we miss by having the sound turned off. Once you turn the sound on, you
get a great deal more meaning from the movie you're watching. The web is
currently a silent movie - using RDFa adds sound to that silent movie,
giving computers, and ultimately you, more meaning from the web."

The opening is too stiff - the primer starts off being an academic read
- it's not exciting unless the words "Embedding Structured Data in Web
Pages" get your juices flowing... and if they do, you need to seriously
re-consider your priorities - :).

We should focus more on getting people excited about what they can do
with RDFa and less time being excruciatingly accurate about what we're
saying. Loosen the language up a bit - the tone should be more
conversational in order to be more accessible.

Section 2.0:
------------

How many people keep a private blog for their friends and family? Most
people I know who blog have a blog for anybody to read, no restrictions.
Should change to "Jo has a blog that is used to keep in touch with her
friends and family."

Strike the term "hacker" - it has negative connotations created by the
damn news media. Replace it with "developer". Appeal to the front-line
laborers of the web, they're the people that are going to put RDFa into
action.

Avoid the use of terms like "explicitly express" and "extracted
consistently".

Section 2.2
-----------

Yipe! Do we really want to introduce the concept of a bnode this early
in the document? Could we do it in Section 2.3? or later? It feels like
we should be introducing @about before @instanceof.

"RDFa" instead of "RDFA".

Section 2.3
-----------

"easy target" - aggressive - use "likely candidate", or "good prospect"

Section 3:
----------

"denote the data's structure" - there's gotta be a simpler way to say this.

Section 4.4:
------------

"The use of @src on an image, as per 3.5 Using @src on img, and the use
of @rev, yields exactly the same triple as if @src were @about:" -
consider re-wording this sentence... it is confusing.

Overall
-------

The document gets the point across. The language/vocabulary used needs
to be dumbed down a bit and the prose simplified. We shouldn't assume
that the person knows about the W3C or cares about standards.

Ideally, the primer document should show them how using RDFa is going
increase their Google rank, help them get a raise at their job and
admiration from their fellow web developers. I realize that is a tall
order, but if we can get people to realize that using RDFa is in their
best interest, uptake will be much faster. In other words, we should be
betting on personal interests and greed to motivate people, not "doing
the right thing".

-- manu

-- 
Manu Sporny
President/CEO - Digital Bazaar, Inc.
blog: RDFa Basics (video)
http://blog.digitalbazaar.com/2008/01/07/rdfa-basics

Received on Friday, 7 March 2008 05:31:17 UTC