Primer review

Overall, I think the primer is in pretty good shape.  I wouldn't recommend 
it as 'ready to ship' in its current form, but most of the edits are minor 
rewordings and clarifications.  I didn't attempt a grammar edit - as I 
think that should probably be done last once there is concensus on the 
content and organization.

General suggestions:

- In every place where a specific GRDDL mechanism is being identified for the example,
   there should be a cooresponding link to the appropriate section in the specification

- The primer could use more diagrams that demonstrate the specifics of the
   example (not just the general GRDDL mechanism) - especially for the
   guitar example which involves quite a bit of machinery and components

- The terminology should be consistent (even if it doesn't use the labels
   we've agreed): the primer goes back and forth between transformations and instructions.

Specific edits:

I agree with Ben's assesment of the introduction, it's a bit lengthy and 
could do without the language about when instructions should be expressed 
in XSLT.  I think removing that as well as removing the last sentence in 
the first paragraph (about the enduring conversation thread on embedding 
RDF) - as Danny suggested - would also help.

(end of Linking to a GRDDL Transform)

"The profile URI in the resulting document signals.."
                                            ^^^^^^^

link to http://www.w3.org/2004/01/rdxh/spec#grddl-xhtml

(Referencing via Profile Documents)

".. is by referencing those instructions from a profile document 
referenced in the head of the HTML."  =>

".. is to identify those <instructions or transformations?> within a 
profile document associated with the XHTML document."

"This method can be more convenient for the content author but requires.."
                                                                ^^^^^^^^

link to http://www.w3.org/2004/01/rdxh/spec#ns-bind

(right before the last code snippet in this section)

"Anyone wishing to get the RDF data out of .." => "A GRDDL <processor or 
client?> can glean RDF data using the Embedded RDF profile associated with 
the XHTML document."

(the paragraph after the last code snippet)

The use of the word 'instructions' doesn't seem as intuitive as 
transformations, perhaps it's mostly because off the inconsistent use?

(Buying a Guitar Example)

Use usecase titles instead of use case #3

"Given a seed URL with XFN data, .." => "Given an XHTML document with XFN .."

"That FoaF file .." => "The extracted foaf <rdf graph|descriptions> .."

I wasn't able to follow specific parts of this example.  In particular, 
it wasn't clear how the FOAF descriptions gleaned from XFN would 
facilitate spidering for additional GRDDL source documents.  It seemed a 
bit out of place and could either use a short paragraph on RDF spidering 
or should be left out if it's not essential to the GRDDL-specific aspects 
of the example.

In addition, the section on identity consolidation via rel="me" was 
unclear to me.  I think a diagram identifying 
these connections between the the source data, and the resulting RDF descriptions 
would make this much clearer and is essential for this example especially.

"Stephan's friend Peter Smith writes several reviews of a new guitars." => 
"Stephan's friend Peter Smith writes several reviews of new guitars"

"We know that the profile page is Stephan's friend Peter by visual 
inspection, ..." => "A human browsing the profile page could tell it belongs to Stephan's friend Peter by visual inspection, .."

"Now a machine can assert that the Peter on the Guitar site, is the same 
Peter that is listed in Stephan's XFN list, which was converted to FoaF, 
because the URLs resolve to the same resource."

Again, I wasn't sure how the identity consolidation works with this 
scenario.

"Using GRDDL is it possible to glean information about the guitar in the 
form of product specifications supplied by the manufacture .." => "Using 
GRDDL is it possible to glean product specifications supplied by the 
guitar manufacture .."

Chimezie Ogbuji
Lead Systems Analyst
Thoracic and Cardiovascular Surgery
Cleveland Clinic Foundation
9500 Euclid Avenue/ W26
Cleveland, Ohio 44195
Office: (216)444-8593
ogbujic@ccf.org

Received on Tuesday, 26 September 2006 16:55:38 UTC