Re: update on Primer

Ben Adida wrote:
> I'm using XML+XSLT to write this, which makes merging your changes
> tough. My brain is also dead from looking at this too much: can you tell
> me what you've changed and I'll do some XML editing?

Hmm... the changes should be color coded in the HTML document that was
attached to my previous e-mail? Did it get stripped from the mail message?

GREEN : Changes (strike-through for deletes)
YELLOW: Comments

Let me know if you'd like the changes in diff form instead, I'd also
need to know where to get the original XML document from...

>> - Fine tune the examples to resonate with a wider audience (talk about
>>   picnics and BBQs, not talks at web conferences)
> 
> That would be a big change in terms of checking all the markup again,
> and coming up with a consistent storyline. I don't think this example is
> all that difficult to follow, is it?

Nope, not difficult to follow - just uses a story that might not
resonate as well with the general Internet community. It's not the end
of the world. I'm sure there will be plenty of other sites, including
rdfa.info, that will outline the primer differently.

>> - Make the language less technical sounding (replace phrases like
>>   "inherent structured data about an event" with "event information")
> 
> I agree with making the language simpler. We do need to keep some
> understanding that things are generic, though. This is not about
> publishing events, this is about publishing structured data, some of
> which could be, for example, an event. That's also a way to mark the
> difference with microformats, which talk exclusively about specific domains.

The only reason that I mention using simpler, more narrow language is
because it is somewhat difficult to grasp generic concepts without a
specific example up front. Then again, everybody learns a bit
differently... just putting in my $0.02.

>> - Split the Primer up into multiple sections on different pages. The
>>   Python Library Reference is a good example of making a large document
>>   seem like an easy read:
>>   http://docs.python.org/lib/types.html
> 
> I don't see the benefit for such a short document. 

It's a short document by W3C standards, certainly :). Readers might not
see it that way, though. Just trying to help them not feel overwhelmed...

> We already have a TOC
> with links to each section. This would also be a big departure from
> existing W3C documents.

I agree, perhaps this would be better handled on rdfa.info?

-- manu

-- 
Manu Sporny
President/CEO, Digital Bazaar, Inc.
http://blog.digitalbazaar.com/

Received on Wednesday, 5 September 2007 04:38:41 UTC