RE: Primer Review

Thanks for another good review.

Harry wrote:
> I'd also *really really* like to have working sample 
> "example" files with data and links to engines like SPARQL 
> and GRDDL implementations which people can run "out of the 
> box", which we don't for much of this tutorial. IMHO that's 
> the main  distinction between the tutorial and the use-case 
> document, so let's do it. Anyone up for helping? However, I 
> won't block the release of this document as Working Draft 
> even though the examples need more work.

Some of the HTML samples are linked in the document. I guess to go
further and link to live services we have to make sure the relevant
SPARQL and GRDDL services have to be at least as persistent as the
primer document. Does the W3C have a public SPARQL server?

> General note: There's lots of sentences like this: "Since XFN 
> values are found on 'a' elements, " that should be formatted 
> like this:
> 
> "Since XFN values are found on <code>a</code> elements," for 
> transparency.

Ok.

> I really want to start the primer off as "easy-to-read" and 
> am so a bit unsure about the rather technical first 
> sentence,primarily because I don't believe it's exactly 
> correct, as RDF is not really KR or meta-data  for many of 
> purposes in our use cases, but just a generalized data  
> format that uses URIs for identity keys for easy aggregation.
> Instead of  starting a primer with a potentially contentioous 
> statement (as well as  referencing an "enduring conversation 
> thread" which most readers of the  Primer may not care about, 
> let's just simplify. I've also think  re-arranging the 
> paragraph breaks a bit makes it bit easier to understand - 
> remember the audience may not be people who read this may not 
> know what "knowledge representation" means nor XSLT mavens.

[snipped intro replacement text]

We have a number of comments about the introduction and perhaps we ought
to address them in a separate thread. I agree it's important that we get
this absolutely right since it's going to be the first thing people new
to GRDDL will read. I propose that we publish as-is and work hard on
getting the intro right for the next draft.

> 2) Scheduling Example
> 
> Who is Jane? :)

Heh. I think I did introduce her at one point but that disappeared.

> 
> "In this use case Jane is trying to schedule a meeting with 
> three other friends."
> ->
> "In this use case a hypothetical user Jane is trying to 
> schedule a meeting with three of her friends."

I prefer to make Jane a little more real than that :) I made her "a
frequent traveller"


> I know it's pedantic, but let's include the DOCTYPE in our 
> HTML example,  since otherwise the user can't cut and paste 
> the example and get it to  validate in the W3C Validation Service:

Done. But I used XHTML 1.1


> And the markup validtor gives this problem with that document 
> [1] as well "on line 19  it contained one or more bytes that 
> I cannot interpret as  utf-8"

Hmmm. Weird. I think there's an encoding issue in my source control
repository. I'll check these thoroughly when I move them to W3C space.

> 
> "The profile URI for GRDDL is 
> http://www.w3.org/2003/g/data-view""-> it would good 
> explaining to add both a period to the end of that sentence 
> and then a sentence explaining what profile URIs are and why 
> they're important/nice. However, I seem to have writer's 
> block right now and can't phrase it right...maybe say "They 
> provide a uniform place for links to transformations and 
> documentation to be stored for web-based vocabularies."

Hmm. I always find it tricky putting punctuation after URIs. I reworked
that sentence. I defined profile like this: "In HTML, profiles are used
to link documents to descriptions of the metadata schemes they employ."

> 
> I'd also add the XHTML DTD to your Embedded RDF example, at 
> least in the linked to example file [2]
> 
> I think it would be  nice if we linked to the W3C GRDDL 
> RDF-in-HTML web service so people  know that it's really 
> running code. [3]

I agree, but see my comment above about persistence. 

> 
> "Then she needs to add a link elemenk" *-> <code>link</code>

Done

> 
> "The link element contains" *-> <code>link</code>
> 
Done


>  It might be useful to show them the RDF produced (maybe in 
> Turtle syntax, with a link to Turtle syntax), or at least 
> have a  link to it.

Yes I'll do this, but I'd like to do it throughout for the next draft


> 
>  Finally, the "scheduling calendar" is sort of anti-climatic, 
> because we just demonstrated to people that we can take 
> microformats and embedded RDF and transform it to RDF/XML. I 
> believe the audience for this document may very well not be 
> people who are ardent RDF users or proponents, but general 
> web masters and "desperate perl hackers" that might want to 
> know why producing RDF is useful - and they may read the 
> tutorial up to this point, say "So What?" and then give up.
> 
> The best way would be by example.  I think it's okay to go to 
> Working Draft in final form, but my (without chair hat on) 
> personal preference would really be to show them that the 
> calendar files can be merged and a meeting scheduled via a  
> SPARQL query.

Ok. We should do that.


That's all I have time to complete at moment. I'll follow up with the
rest of your comments asap.


Ian
 
The very latest from Talis
read the latest news at www.talis.com/news 
listen to our podcasts www.talis.com/podcasts 
see us at these events www.talis.com/events 
join the discussion here www.talis.com/forums 
join our developer community www.talis.com/tdn 
and read our blogs www.talis.com/blogs 
Visit Talis at this year's PLA Conference, 11-13th October 2006. We plan to showcase new product enhancements and unveil new initiatives. 


 
Any views or personal opinions expressed within this email may not be those of Talis Information Ltd. The content of this email message and any files that may be attached are confidential, and for the usage of the intended recipient only. If you are not the intended recipient, then please return this message to the sender and delete it. Any use of this e-mail by an unauthorised recipient is prohibited.

Received on Wednesday, 27 September 2006 13:23:40 UTC