Re: RDFa DOM API - New Editor's Draft

Manu,

I think this is shaping up really well. I have some minor technical comments below; but I am now looking at the table of content. 

It seems that section 2 and 3 are really the essential overview for users, without going into the IDL details. The structure and 'story' looks quite fine to me there. It may be worth and clearer to the reader to group them in one section.

I have a problem with the word 'high' and 'low', however, that is used as section heading and also in the document. What is now section 5 is not a section on low level interfaces; as far as I can see, that is the section on the formal, detailed specification of all interfaces, isn't it? Also, I am not sure why the content of section 4 is 'high level'.

Let me play with a minor rearrangement:

1. Introduction (as is today)
2. Using the RDFa
   Design goals (current 2.2.1)
   concept diagram (current 2.2.2)
   Basic usage (new section)
     The Web developers API (current 2.1)
     Working With property Groups (current 2.2.3(
     Managing elements with data (current 2.2.4)
   Advanced usage (new section, content of current section 3)
3. The WebIDL definition (the whole of section 5, just the title of the section changes)
4. Initializing the environment
   current section 4
--- rest of the sections ---

(I must admit I am not sure about the current section 4... 


How does that sound?

--------------------
Additional comments:

- Concept diagram, 2.2.2: it is good to have, but somehow it should be made clear to the reader that the three arrow represent, in fact, and increasing level of sophistication but an average user does not have to know about, say, the data store. I wonder whether creating three diagrams (1: webapp, doc, property gorup 2: like 1 plus data parser and query and 3: like 2 plus data store &co) would make that clearer. (I know the info is in the text, but people might look at the diagram first...)

- right before section 3, the heading says "using property groups". Is that correct? We are talking about elements here...

Actually, the example uses e.style.setProperty which is, I presume, the way to set a CSS property. But then... using 'Property' for our Property groups become really really confusing! I wonder whether the example was on our properties or not. Bottom line, we should find another name for Property Groups (though I do not know what...)

- this is just editorial: I am a bit mixed what we call high or low:-( Around the concept diagram you refer to the query part as 'low level'. In the intro of 3 you refer to 'high level':-(

- this becomes a technical detail, but... why does the definition of RDFTriple use these indeces? why not something like

interface RDFTriple {
   readonly attribute Object subject ;
   readonly attribute Object predicate ;
   readonly attribute Object object ;
}

the usage of these indices just remind me of FORTRAN programs:-(

- I need some education on the role of DataIterator in a DataParser. My mental model seems to be too simple: I would expect a parse operation to be defined on a DataStore, so that I say

store = new DataStore() // or whatever the syntax is
store.parse("http:....")

and that is it.

I obviously miss something...

Cheers

Ivan




On May 26, 2010, at 07:32 , Manu Sporny wrote:

> I've integrated much of Ivan's feedback on the presentation of the DOM
> API document as I could. He'll need to look at it again to ensure that
> it's going in a direction that is acceptable.
> 
> Pay special attention to the table of contents, see if the layout seems
> appropriate.
> 
> http://www.w3.org/2010/02/rdfa/drafts/2010/ED-rdfa-dom-api-20100526/
> 
> I tried placing the IRI/Plain Literal/Typed Literal/Triple stuff at the
> beginning of the document and it just didn't work. It required a ton of
> explanation up-front and it made the introduction to the API fairly
> heavy-weight.
> 
> The sections are kept light on purpose - until all of us agree on a
> structure, there isn't much use in filling each section out to make the
> document flow better. I'll respond to Ivan's e-mail in a separate document.
> 
> This is just a heads-up that the RDFa DOM API has been re-arranged to
> address some of the concerns raised on the telecon last week.
> 
> -- manu
> 
> -- 
> Manu Sporny (skype: msporny, twitter: manusporny)
> President/CEO - Digital Bazaar, Inc.
> blog: Bitmunk 3.2.2 - Good Relations and Ditching Apache+PHP
> http://blog.digitalbazaar.com/2010/05/06/bitmunk-3-2-2/2/
> 


----
Ivan Herman, W3C Semantic Web Activity Lead
Home: http://www.w3.org/People/Ivan/
mobile: +31-641044153
PGP Key: http://www.ivan-herman.net/pgpkey.html
FOAF: http://www.ivan-herman.net/foaf.rdf