[ACTION-373] Review Chris' changes to API document (done)

Dear all,

at first i want to wish you all the very best for the new year 2011! I hope you all had nice holidays!

The last two days, i found enough time to get into the new API document and to come up with some thoughts about it. At first i must admit that i was pretty confused in the beginning. This was more or less because of the Call-By-Reference definitions and the "strong" differentiation between sync and async. Nevertheless, i think Chris made a great work here, but we have to do a few changes to improve things.

I made several comments, more or less concentrating on the first sections. For me, the main issue is the description or better the explanation why we differ between sync and async like we do now - i tried to explain myself bellow. I also think, sync and async should be also reflected in the use case scenarios. So, i have attached my comments to the document below.

Cheers,
Florian

============================================================
============================================================
= Notes on API for Media Resources 1.0 (W3C Editor's Draft 05 January 2011)
============================================================
============================================================

=====available at:
http://dev.w3.org/2008/video/mediaann/mediaont-api-1.0/mediaont-api-1.0.html

===========
===== Abstract
===========
 - "This specification defines a client-side API to..."
    Delete "client-side". In section 2 we state, that this API can also be a WebService,
    which is not located at the client.
 - "The overall purpose of this API is to provide developers with a convenient access
    to metadata information stored in different metadata formats."
    I think we should state, that the actual access to the metadata is not defined by us.
    Only interfaces and the object structure of our pivot format. From my point of view,
    the abstract a is is misleading.

================
===== 1 Introduction
================
 - "This specification defines a client-side API..."
    More or less the same issues as outlined for the abstract.
 - "This API serves as a mediator between a developer and the Ontology for Media Resources
    1.0 [MEDIA-ANNOT-ONTOLOGY] with the goal of supporting interoperability between 
    metadata formats."
    Proposal:
    This API defines/exposes interfaces that enables users/applications to consume metadata
    in a interoperable manner. Here, interoperability between metadata formats is ensured by
    the use of the Ontology for Media Resources 1.0 [MEDIA-ANNOT-ONTOLOGY] as pivot
    metadata format.

=========================
===== 2 Design Considerations
=========================
 - insert caption for Figure 1
 - Figure should be smaller and inserted before the sceanrio description
 - we now have sync and async modes of communication...should we reflect this also in the
   scenarios? Maybe make a third one that cleary shows the need for an async call!
 - Bullet 3: clearly state here, that it is not part of our spec how the metadata access is done!

=========================
===== 3 Design Considerations
=========================
 - "This API has a number of interfaces that represent media resources, media annotations,
    and metadata sources, described using Web IDL."
    This sentence carries no information. Proposal:
    This API defines a number of interfaces that can be grouped in the following categories:
        * interfaces defining the actual retrieval methods (GET) for metadata
        * interfaces defining the structure of metadata objects/annotation
        * interfaces defining the metadata source
    These interfaces are specified by the use of WebIDL.
 - We should clearls state, that the API is mostly based on Call-By-Reference...this will improve
    readability!
 - Why does the API description start with the description of the MediaResource interface?
    Proposal:
    Make a new Section 3.1 MediaResource interface, here we can put the general description
    given in the beginning of Section 3. Make two subsection 3.1.1 Sync mode 3.1.2 async
    mode.
 - 3.1: Change the ordering of the content. First come up with the WebIDL definition, afterwards
    the example. Nevertheless, there is a example section with nearly the same example. Could
    be also deleted here (would propose from "obtaining" until "media resource").
 - "Next, we give some JavaScript..."
    wrong styling
 - 3.2 same remarks as for 3.1 since it is the same text. from my point of view, we have to state
    how this implementation is different from sync mode...this has to be revised i guess
 - regarding sync and async: from my point of view, it is really valuable to have these two modes.
    but now, we are a little bit weak from the point their differentiation. We have to discuss things
    like "Why do i have to implement the sync mode? i could implement the async mode and fetch
    immediately the answer!" So for guys like this, there would be only one mode serving both.
 - "Next, we give some..."
    wrong styling
 - 3.2 i think all the callback things should be explained a little bit more...this part is confusing

==============
===== Appendix A
==============
 - "DOMString getPropertyNamesHavingValues (DOMString[] propertyNames, ..."
    missing "in"?

Received on Wednesday, 5 January 2011 11:01:39 UTC