Re: Status of the API Doc v1.0

I think that it is a very nice start for the API paper, but maybe a  
section about different possible implementations would be nice? This  
is why I thought that the content of the current paper could be  
fitting as content part of this document. If you all agree that the  
paper is more on the ontology side, then I suggest to add one section  
about ontology and mapping implementation methods/formalisms in the  
ontology document itself. I think it would be a pity not to have the  
official documents benefitting from some work done in collaboration  
within the group. another possibility is to add an "ontology and  
mapping implementation for different API strategies" in this document,  
on top of what Chris suggests as an outline.

Best,
Véronique

On Sep 8, 2009, at 11:37 AM, Chris Poppe wrote:

> Dear all,
>
> I have  been thinking a bit on the API-document, more specifically  
> on the content. As I see it, it would make more sense to put section  
> 4 (API description) before section 3 (Data type description). Hence  
> the document would have following structure (I also give a brief  
> description of each section as how I would see the API document):
>
> 1.       Abstract
> 2.       Introduction: reason why we want to provide an API and an  
> explanation on who should use/implement it.
> 3.       API description: a precise description of the actual  
> methods in the API, (so these are the methods that can be found in  
> the Strawman API design [1]), described using web IDL. Victor has  
> already sent an excellent example (using IDL). This section needs to  
> define and explain all aspects of those methods (parameters and  
> return values).
> 4.       Data type description: Here we discuss for each property in  
> the ontology what the specific return values are.  (for example if  
> we call the GetStructuredValue method for property ma:creator, what  
> would be the structure and content of the result (so in fact a kind  
> of Javadoc style)). The examples that were added to the summary  
> table [2] are an obvious starting point and should also be repeated  
> in this section to clarify what is meant.
> 5.       Examples of how to use the API: Here I think we should  
> discuss actual (working) implementations that implement this API.
>
> Not everything has been decided upon (which methods, return values,  
> etc. ). However, the document will be a good (imo better) starting  
> point for further discussions on this topic. I also believe that it  
> might be difficult to use the paper that is currently being written  
> as a first version of the API doc. Presumably, only the introduction  
> can benefit from the paper but the contents of the paper is actually  
> more on the ontology and ways to define the mappings.
>
> I would happily volunteer in sections 3 and 4 but I would like to go  
> through the web IDL specification first.
>
>
> [1] http://www.w3.org/2008/WebVideo/Annotations/wiki/Strawman_API_design_and_notes
> [2] http://www.w3.org/2008/WebVideo/Annotations/drafts/ontology10/WD/summary.html
>
> Kind regards,
> Chris
>
>
>
> From: public-media-annotation-request@w3.org [mailto:public-media-annotation-request@w3.org 
> ] On Behalf Of ???
> Sent: dinsdag 1 september 2009 4:27
> To: Florian Stegmaier; Victor Rodriguez Doncel; Chris Poppe
> Cc: public-media-annotation@w3.org; ???
> Subject: RE: Status of the API Doc v1.0
>
> Dear Florian and All,
> We are just in the starting point for preparing API doc because of  
> vacation season.
> So, It’s time to hardly work for reaching to our goal. ;) I think  
> we have to make early version of first draft until 15th September.
>
> Below is the structure we had and I describe proposal how to  
> describe each part. If anyone have better ideas, please let me know.
> In addition, I am looking for volunteers for each part. Please let  
> me know.
>
> 0.     abstract à need to make first draft
> 1.     Introduction à need to make first draft
> 2.     Terminology à firstly add the terms from ontology doc if we  
> need. And then add additional terms if we need.
> 3.     Data type Description à Do anyone have ideas ?
> 4.     API Description à After referred Strawman API design and  
> notes page[1] in wiki, describe draft APIs based on the core  
> properties of ontology doc.
> 5.     Examples of how to use the API(in Java for example(chris),  
> web IDL) à I think it could be covered later after mature of APIs.
>
> [1] http://www.w3.org/2008/WebVideo/Annotations/wiki/Strawman_API_design_and_notes
>
>
> Best regards,
> Wonsuk
>
> From: Florian Stegmaier [mailto:stegmai@dimis.fim.uni-passau.de]
> Sent: Monday, August 31, 2009 11:33 PM
> To: 이원석; Victor Rodriguez Doncel; Chris Poppe
> Cc: public-media-annotation@w3.org
> Subject: Status of the API Doc v1.0
>
> Dear all!
>
> I wanted to know, if there is already a progress on the API Doc v1.0?
>
> Should we start working on the outline proposal of Wonsuk? Who will  
> be in charge of coordination and the yet defined parts?
>
> I think we should keep in mind, that the first deadline is preety  
> near (early October) and we should initiate the work on it asap.
>
> Best,
> Florian
>
> _____________________________
> Dipl. Inf. Florian Stegmaier
> Chair of Distributed Information Systems
> University of Passau
> Innstr. 43
> 94032 Passau
>
> Room 248 ITZ
> Tel.: +49 851 509 3063
> Fax: +49 851 509 3062
> stegmai@dimis.fim.uni-passau.de
> _____________________________
> Quote of the week: Computer. This is a Class-A compulsory directive.  
> Compute, to the last digit, the value of pi. (Spock)
>
>
>
>
>
>