Comments on Primer draft

Looking at:
http://research.talis.com/2006/grddl-wg/primer

General Points
============
Overall: looking good, probably acceptable for public review already,
some suggestions -

Noticeable for its absence is an example of the triples obtained by
passing a profile through data-view. Maybe include a sample towards
the end of "Referencing Via Profile Documents".

It probably isn't essential for this release, but it would be good to
see an example of a source format other than XHTML (reminds me I
really must finish that Atom XSLT...)

The material ends rather abruptly - could do with a line of conclusion
and described links for further reading (in addition to the formal
references).

Specific Sections
=============

*** Abstract ***
"a mechanism for getting RDF data out of XML documents" doesn't sound
right - maybe "a mechanism for obtaining RDF data from XML
documents"..?
s/appropiate/appropriate

*** Introduction ***
I think this could start more gently, I really don't know, maybe some
of it could be moved later in the doc..? It should at least be
possible to appeal to the microformat's target audience a little more,
maybe add at the start something like: "GRDDL gives content providers
a means of including explicit data in their documents, using their
current formats and in many cases without significant changes to the
markup. For consumers of Web data, it offers a more dependable (?)
mechanism than screen scraping".

"address very separate and often orthogonal problem spaces" - I'd drop "very"

"The enduring conversation thread on embedding RDF in XHTML" -
although this makes a lot of sense to people that have been around RDF
a while, it may be confusing to anyone else, I'd be tempted to drop
the sentence.

"In this document the term HTML is used to refer to the XHTML dialect
of HTML." - Which dialect of XHTML? (sor-ry ;-)

Near end of Introduction I think it could do with a sentence something
like: "GRDDL works through associating transformations with an
individual document either through direct inclusion of references or
indirectly through profile documents.

*** Linking to a GRDDL Transform ***

Seems a little confusing saying there are a number of ways of making
the association, then giving example code without an association -
maybe shift first para after HTML?

One-line definition of microformats might be an idea - "(Microformats
[http://microformats.org] are simple conventions for embedding
semantic markup for a specific domain in human-readable documents)

Add link on hCalendar to http://microformats.org/wiki/hcalendar

"The simplest method for authors of HTML content is to embed a
reference to the instructions using a link element in the head of the
document." - s/instructions/transformation instructions...? Or
"processing instructions"?

Probably needs something like an italic note below the diagram saying:
"Although it's convenient to show the GRDDL process as a procedure, it
is defined declaratively as a functional process and implementations
may vary significantly from the steps shown above"

*** Referencing Via Profile Documents ***

s/instructions/transformation instructions...? Or "processing instructions"?

Maybe add an italic note below this diagram, "As with the previous
diagram, a typical implementation might not follow the procedure
shown, for example the profile transformations may be cached locally".

*** Buying a Guitar Example ***

"FoaF and vCard-RDF are both suitable sources to extract the data
from. " => "FOAF and vCard/RDF are suitable expressions of the data."

(Norm's hcard2rdf.xsl is linked from http://www.w3.org/2006/03/hcard)

s/snippit/snippet

"XFN is the HTML friends network. Using values in the rel
attribute..." => "XFN is the HTML friends network. Using values in the
rel attribute of links..."

hCard link: http://microformats.org/wiki/hcard

s/FoaF/FOAF several times

s/URLs/URIs (*cough*)

"The Del.icio.us links..." => "For example, the del.icio.us link..." ?

"example.org" would probably be better more specific (and with http://)

s/marked-up/marked up

"We know that the profile page is Stephan's friend Peter by visual
inspection, but a machine does not." - sounds clunky, reword..?

"The first restriction on the data can be a pass on review data such
as rating" => "The first restriction on the data can be a check (?) on
review data such as rating."

"This SPARQL result is in XML or JSON and can easily be consumed by
another application." => something like "SPARQL results can appear in
XML or JSON and can easily be consumed by another application."


-- 

http://dannyayers.com

Received on Wednesday, 20 September 2006 17:19:32 UTC