Re: Status of the API Doc v1.0

Dear all,

I think Chris agenda is a good step towards defining "where we want to  
go" exactly with the document. We should use the todays talk to  
determine some starting points. I also thought about the the document.  
On the basis of Tobias proposal to look at [1], i thought we could  
split the introduction like in [1] into "intro" and "scope" (but scope  
with a different meaning). So, in our document, Sope could server as  
an explanation whom we want to address with it and why it would be  
good for these people (as Chris suggested for the introduction).  
Perhaps we can find even more useful things for our draft in [1].

I agree with the "previous speaker", that the paper, which is  
currently written, is not in the scope of the API document, but offers  
an valuable input for the Ontology Doc v.2.0. As i remember, Victor  
wanted to write something about a possible API...i don´t know if he  
did it...perhaps he can give us a short overview of the status on it.  
His paper would better fit into the work on the W3C API document i  
guess.

Hear you in todays Telecon and i´m looking forward to a great  
discussion!

Best,
Florian

[1] http://dev.w3.org/geo/api/spec-source.html

Am 08.09.2009 um 12:03 schrieb Veronique Malaise:

> 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)
>>
>>
>>
>>
>>
>>
>


_____________________________
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)