Proposed Plan for Web API work

We will discuss this all on tomorrow's main HTML Speech call, but here is my proposed plan for tackling the Web API work (please read at least through the participants section, even if you aren't part of the API track):


1.       Clarify who's interested in participating in the work, and how to work moving forward

2.       Confirm agreement on basic design approach

3.       Review design decisions and agreements that relate to API.

4.       Come to consensus on functionality of API items/functions/data/etc and document crisply.

5.       Confirm the naming of API items/function/data/etc.

6.       Add text to the Proposed Solution document reflecting our consensus agreements (or any places where there is clear alternatives without agreement)

I expect us to be completely finished 1 and 2 by the end of tomorrow's teleconference, and I expect that different parts of the API will speed through steps 3 through 6 at different rates.  So we may already have how to specify grammar in the Proposed Solution while the way to specify the speech service might still be at step 4 (or vice versa).

Participants:
For who the participants are, the minutes of the F2F (http://www.w3.org/2005/Incubator/htmlspeech/2011/05/f2fminutes201105.html#tuesday_pm2) have myself, Michael Johnson, Bjorn Bringert, Dan Burnett as the only participants.  However, I thought I remembered Debbie Dahl and Olli Pettay as volunteering as well.  So I'm tentatively saying our participants are all of the above (and those folks are on the to list); however, if you are not there but would like to add yourself to the participants, please send email or speak up in tomorrow's call (and same thing if you are currently listed but would like to remove yourselves from the call).

Work moving forward:
For how to move forward, I think it would be best to try to focus on email discussion if possible.  We will have a regularly scheduled HTML Speech call for our effort roughly every 3 weeks (first one June 9th, next one June 30th).  If we want we can try to find additional weekly teleconference time (probably the 30 minutes after the call would be most likely to be free, since Protocol track already grabbed the 30 minutes before), but I think given how late that is in Europe combined with summer/paternity meaning regular times may be tough, I'd rather we try to concentrate on email.

Basic design approach:
Our basic design approach is scripting, and we've agreed to that.  The only basic design approach that is still unresolved is the issues around the existence of an html element for reco, but what I'd like to propose is that we consider our speech JS Object possible optionally a markup element and that we have an associated for attribute, defined as the html5 label/@for is defined (complete with the htmlFor IDL attribute).  We should spend only enough time writing this part up such that it is clear to folks what it would do if we support it, but shouldn't deep dive on the details (for instance the details around automatic grammars or element filling or what the user interface exposed is and how that varies by different elements).  We should not add this part of the API to the Proposed Solution without documenting that there are objections to it (assuming those objections still hold).  Fortunately, I think the rest of the API stands on its own even if the element and htmlFor is removed from our work, so I think it really can remain this orthogonal (documented, with the objections also documented).

Review design agreements:
It would be great to have someone go through the design agreements and pull out the ones that apply for the API, similar to what Marc did for the protocol.  Any volunteers?

Come to consensus on functionality:
For the rest of the work, which hopefully is mostly uncontroversial, I think it is right to start from the design decisions (and possibly requirements, use cases, and proposals) and produce IDL similar to what Bjorn sent in the mail http://lists.w3.org/Archives/Public/public-xg-htmlspeech/2011May/0013.html and also text explanation. The IDL is important as it forces us to a next level of detail and crispness, and is a format that will be part of the final solution. The text explanation, however, is also very important as we've already discovered a bunch of subtleties, for instance around the timing of the endpoints, marks, and bargein, which would not be made clear by the IDL alone.  Until we have the text describing the API, and the right IDL (in terms of which parameters of which functions, which event handlers, etc.) I'd like to mostly avoid naming discussions (I.e., maxnbest versus maxresults versus numresults etc.).  Conflating naming discussions and functionality discussions makes both difficult to achieve.

For some of the things we talked about at the face to face we may be ready to jump right into the IDL and the text.  I don't think we should start with Bjorn's IDL proposal (although I do think we should be inspired by it and borrow strongly from it) just because we know there were issues raised at the face to face (and on the email list) around only one grammar, the way language was expressed, etc.  Does anyone want to volunteer to try and write the IDL and text reflecting the API discussions from the face to face?  It is ok if we wait until we've collated and reviewed the design decisions, but I think we could probably move in parallel and use the design agreements more to fill in the gaps and refine an IDL based proposal.

Come to consensus on naming:
It is important to agree on naming eventually.  I'd like to make this explicitly a step in the process so that everyone knows we will do it (so people don't need to flip out over "bad" names), but capturing it separately.  It also helps give us a natural pause between thinking we have consensus on functionality and getting that reflected in the Final Report Document.

Proposed Solution:
The final output of this process is text in the Proposed Solution section of the Final Report.  I've updated the report to have a separate section for API versus protocol to enable us to start editing as soon as we have consensus.