Re: [hybi] List of (mostly) editorial changes for draft-01

[Patrick McManus <[e-mail]>]

Hi John, thanks for reading the long list and providing feedback.

> Maybe there needs to be a separate document with the rationale, [..]
> but this and other statements were intended to make clear the
> rationale for the choice

right, that's a recurring theme of the proposed edits. I think the
result is that an implementor reading the document has a more concise
view of what she needs to do to get it right.

The document is not trying to win a debate, explain the history of every
bit, or change minds - the mailing list archive or (as you suggest) a
separate non standards track document can persist for those purposes.

I'm not opposed to a few statements of rationale here and there when
they provide useful advice to implementors, but the primary focus of a
standards track protocol specification is to provide a clear definition
of what the protocol requirements are for interoperation and quality
implementations.

In cases where a specific element can benefit from some nuance (for
instance a hypothetical "SHOULD create large fragments") then go for the
explanation, but in most cases it really just opens up a can of worms
and clarity is added by constraining the document to what is necessary.

here is an example:

"The base framing protocol is deliberately kept simple so that simple
implementations may ignore advanced features."

Hypothetically I begin my implementation of a websocket server from the
specification and I find 64 bit lengths difficult to work with. Suddenly
ambiguity sets in. Is 64 bit lengths an advanced feature? Can I ignore
it? Am I a simple implementation - what's the definition of that? If I
know I'm an advanced implementation in some other aspects does that
prohibit me from ignoring this requirement? Obviously, I figure out that
I cannot ignore it and interoperate on the web even though this text
tells me I can ignore advanced features! now the standard is internally
inconsistent. yech.

We could try and fix those problems in the text, or we can ask in what
way the goals of interoperation and quality implementations damaged by
just removing it from the specification. 

The most borderline of the cases in my mind involves removing the
rationale from "a sender MAY fragment a message". The way the text was
written created one interpretation where a sender may fragment it in
order to generate dyanmic content but it isn't clear if there is then
permission from the spec to do it for other reasons.  I think it states
the requirements more clearly if the rationale is left out, the sender
MAY do it. Period. But of course the rationale can always be reworked if
it provides useful advice and as I said this was probably the most
borderline of the ones I cited.

> or perhaps they can be kept inline in the draft with the understanding
> that they will not be present in the final version,

I would object to this approach - we have lots of issue trackers that
can track the reasons behind various decisions. Its high time to start
moving the document towards its submission state and using the document
and specific proposed changes to it as a focal point for working group
discussions.

-Patrick