Re: [Recipes] new editor's draft

Thanks Ed. Great review!

More inline below...

--Jon


On May 26, 2008, at 9:50 PM, Ed Summers wrote:

>
> Hi Jon & Diego:
>
> I finally got round to reviewing the recent changes [1]. Since most of
> the changes this time included rewriting URLs I focused mainly on
> them.
>
> In general I was wondering if the examples and the steps should to be
> consistent in the use of  URLs as they were in the previous working
> draft of March 14th, 2006 [2]. At the moment the examples for each of
> the recipes seem to use a location of:
>
>   http://www.w3.org/2006/07/SWD/recipes/examples-20080421/
>
> Whereas the steps for each recipe use:
>
>   http://yourhost.com/examples/
>
> I think I would prefer the steps in all the recipes to be consistent
> in the host and paths from the examples. This would include the sample
> HTTP requests as well. At the very least I would recommend using
> example.com or what have you, instead of yourhost.com.

I _think_ that the only place where we use 'yourhost.com' is in the  
test messages and response for each recipe. My help-desk experience  
tells me that we can't use the resolvable W3-space URI because people  
will just copy the test URI, get the documented response (which will  
tell them nothing of value) and call it a day. We could certainly use  
example.org, although it would seem to me to be less clear that they  
should substitute the correct host location of their own files. On  
the other hand, if I'm correctly assuming a lack of understanding to  
that degree, nothing could be sufficiently clear.

Unless Diego or Ralph has an objection, I'm fine with changing  
'yourhost.com' in the released doc to 'example.org' wherever it occurs.

>
> In addition there were some problems with the files being served up  
> at w3.org:
>

[snip]

> I think if it's too much trouble to get the server side files correct,
> perhaps the easy thing to do would be to simply use example.com
> throughout. I think having non-resolvable examples would be preferable
> to resolvable but broken examples.

We emphatically agree!! (says Jon, presumptuously speaking for Diego  
as well) -- correct examples are definitely what we're trying to  
provide. Thank you so much for the fine-grained checking. I've fixed  
all instances of 'isegserve'-based URIs in the documents, replaced  
the example1.rdf and example2.rdf files, and corrected all instances  
of incorrect capitalization of 'class'.

>
> LastIy I got to thinking that RDFa + GRDDL would provide a really nice
> way of publishing human and machine readable versions of a RDF
> vocabulary in one document without having to play around with any
> content negotation. But I realize this is the 11th hour, and there
> probably isn't much time to do this. Perhaps it could be another note,
> if someone were to find time to do this? I guess RDFa hasn't made it
> through the REC process yet, so maybe this is premature.

An excellent point, but I think we already decided that providing  
recipes for RDFa and GRDDL was out of scope (for this version of the  
document at least) and inserted the following to cover that  
particular portion of our posterior:

"Finally, it should be noted that the Recipes described in this  
Cookbook are not the only way to publish a vocabulary or ontology for  
use by Semantic Web applications. RDFa and its cousin GRDDL may in  
the near future provide an effective method for publishing documents  
for use by both people and machines. But a useful discussion of RDFa  
and GRDDL is well beyond the scope of this document."

>
> //Ed
>
> [1] http://www.w3.org/2006/07/SWD/recipes/draft-20080421.html
> [2] http://www.w3.org/TR/2006/WD-swbp-vocab-pub-20060314/
>

Received on Tuesday, 27 May 2008 17:21:25 UTC