[mediacapture-main] Wording concern about the text describing the add track and remove track algorithms

a2sheppy has just created a new issue for 
https://github.com/w3c/mediacapture-main:

== Wording concern about the text describing the add track and remove 
track algorithms ==
I've been working on documentation updates for MDN around media stuff,
 and ran into an issue yesterday which I worry could throw off others.

First, the way the add a track and remove a track algorithms are 
described right after the note box in section 4.2 of the spec is 
confusing because the each operation (adding a track and removing a 
track) is described twice:

    "To add a track to a MediaStream , the User Agent MUST run the 
following steps..."
    "To remove a track from a MediaStream , the User Agent MUST run 
the following steps..."

    "When the User Agent initiates adding a track to a MediaStream , 
with the exception of initializing a newly created MediaStream with 
tracks, the User Agent MUST queue a task that runs the following 
steps..."
    "When the User Agent initiates removing a track from a MediaStream
 , the User Agent MUST queue a task that runs the following steps..."

This is a key source of confusion. It makes sense that there are two 
algorithms for each of these, since the operation differs depending on
 how the track addition or removal is initiated, but they're separated
 so that you see add then remove then add then remove. That means 
context is lost, and if you don't read on after the first remove, you 
may not catch the existence of the second algorithm.

On top of that, the wording is very tricky here. The first sentence 
means "For the user agent to add a track to a MediaStream, it 
must...". The third one means just about exactly the same thing, 
unless you understand that the first one is actually meant to mean 
"When a script adds a track to a MediaStream, the user agent must..." 
and the third one means "When the user agent initiates the addition of
 a track to a MediaStream, it must..."

That difference is not obvious when reading this text. You have to 
have some advance knowledge of how those phrases are meant to be 
interpreted, and I'm not sure it's wise to assume that everyone 
reading a specification will parse writing like that the way it's 
intended to be parsed. I certainly didn't. Took me several minutes of 
re-reading to catch on to this interpretation. :)

Finally, a direct quote from the description of the addtrack event:

    "A new MediaStreamTrack has been added to this stream. Note that 
this event is not fired when the script directly modifies the tracks 
of a MediaStream ."

The text "this event is not fired when the script directly modifies" 
suggests that the event isn't fired when a script adds a track by 
somehow bypassing of the addTrack() method, which isn't what's 
intended here. It actually means that the event isn't fired if you use
 addTrack(), which is exactly the opposite.

Anyway, I worry when the way specs are written leaves stuff open to 
interpretation so I try to point out things that I find unclear, like 
this one. It's really easy to interpret when the events should be 
fired exactly backward from what's intended, and that makes me nervous
 enough to point it out. :)

Please view or discuss this issue at 
https://github.com/w3c/mediacapture-main/issues/388 using your GitHub 
account

Received on Wednesday, 31 August 2016 21:12:30 UTC