Re: JavaScript API on top of SDP

Hi Harald,

On 17/07/2013 5:42 AM, Harald Alvestrand wrote:
>>
>>  1. Section 4 states: "It is assumed that the user applications are
>>     executed on a browser". This assertion flies in the face of many
>>     of our use-cases.
>>
> I think I have to ask you to explain that. As far as I can tell, every 
> use case in that document executes on a browser (but often 
> communicates with non-browser components).

     I argue that there is a very high demand for mobile to mobile 
communication (no browser involved) and headless (server) peers. WebRTC 
1.0 should take that into consideration, even if the native API only 
ends up as part of WebRTC 2.0.

>>  1. Without API examples, there is no feedback mechanism of how
>>     good/bad the API fits our use-cases. Recent conversations
>>     highlight why need such a mechanism.
>>
> But those examples don't belong in the use cases and requirements 
> document; they might belong in a document showing how the API 
> satisfies the use cases.
>>
>>  1. The document fails to explain the reasoning behind the design
>>     decisions that were made.
>>
> The -overview document is the place to explain design decisions. Use 
> cases documents are not supposed to be the place where you make 
> design; they guide design, they don't mandate it.
>

     I am expecting a one or more (ideally one) document that will:

  * Enumerate the use-cases.
  * List one or more APIs that satisfy each use-case.
  * Reference one or more unit tests for each use-case which demonstrate
    how the API implementing the use-case.
  * Enumerate the design decisions, referencing one or more use-cases as
    justification.
  * It's perfectly alright to list design decisions without use-cases as
    justification, but obviously it is much easier for the community to
    suggest alternatives in such a case.

     If you do this, you will get a good feedback mechanism between 
use-cases and the API design. If you find that typical use-cases result 
in a very convoluted code then you will know that the design needs to be 
refactored. It also saves a lot of unnecessary discussion on the mailing 
list, as you can answer most questions by pointing people to this document.

Gili