RE: [MSE] Spec writing guidance for splicing bugs

I recommend you aim the MSE spec at implementers.

If there is a need for documentation for developers that would use an implementation we could a) leave that to the implementers or b) consider doing a higher level MSE primer.

/paulc

Paul Cotton, Microsoft Canada
17 Eleanor Drive, Ottawa, Ontario K2E 6A3
Tel: (425) 705-9596 Fax: (425) 936-7329

From: Aaron Colwell [mailto:acolwell@google.com]
Sent: Thursday, January 31, 2013 2:34 PM
To: <public-html-media@w3.org>
Subject: [MSE] Spec writing guidance for splicing bugs

Hi,

I've started looking into addressing the various splicing related MSE bugs and I would like to get some advice on spec writing best practices.

As some may recall, early versions of the MSE spec had text descriptions of various behaviors and then algorithmic descriptions that basically covered the same territory. Many of Philip's original comments had to do with inconsistencies between these two descriptions and it was made clear that just having the algorithms describe the behaviors in a normative form was preferable. This made the spec much easier for me to maintain and I believe it made the behavior descriptions much more precise. The side effect of this though is that some high level behaviors many not be clear from the low level algorithm descriptions.

For example, part of Bug 19784<https://www.w3.org/Bugs/Public/show_bug.cgi?id=19784> strives to clarify how a splice with multiplexed content works. There has been a little discussion around an image that describes the intended behavior. Except for the cross-fade behavior and a missing coded frame removal step, the coded frame processing algorithm<https://dvcs.w3.org/hg/html-media/raw-file/default/media-source/media-source.html#sourcebuffer-coded-frame-processing> covers how timestampOffset is applied and causes splices to be resolved on a per track basis. This may not be as obvious as the image in the bug indicates, but it is there.

So here are my questions:
- What is an acceptable amount of duplication/alternate explanations I should have in the spec text?
- Who is the MSE spec's primary audience? Implementers or content creators? Obviously since Philip, Adrian, and myself are implementers, I've been focusing on being precise about the algorithmic aspects and less focused on easy to understand higher-level pros descriptions of certain behavior.
- If alternate explanations are common/expected, will people please provide some good examples in other specs that I can draw inspiration from?
- Are there other examples of how to clearly mark non-normative sections? If there are to be alternate explanations that aren't considered normative, I'd prefer them not having to be in a giant green box. :)


Thanks for your help,
Aaron