Subject: Re: [quicwg/base-drafts] Restructure document (#411)

From: mirjak <[email-masked]>
Date: Thu, 16 Aug 2018 09:07:30 -0700

I did a fully review of transport-14 and can confirm that the current organization is not super great as a lot of concepts you need to understand the details are explained too late in the doc. Also I noticed that the QUIC overview section was removed on -11. I agree that the text in that section was not great but I think it would help a reader, who is not familar with quic, a lot to have a (non-normative) section first explaining the main concepts (multiplexing/streams/frames, how encryption works/session resumption, reliability/packet numbers, maybe also flow control, migration, and versioning).

Here are a bunch of micro re-org suggestions based on -14 (however I agree with the general stuture @martinthomson prposes above which at minimim would mean to move section 8 much earlier in the doc):

- section 5 (Frames and Frame Type) should be merged with section 7 (Frame Types and Format): I guess the intention was to provide the reader a full list with all frame types early on. That was actually rather confusing than helpful. I think it is okay to just provide a reference to the respective section later in the doc whenever a frame type is mention that was not introduced yet.

- I would recommend to merge the text in section 6.6.3 (New Transports Paramters) just in the intro text of section 6.6. (Transport Paramter)

- Section 6.7 (Stateless Retry) needs to show up earlier in section 6 because it is mentioned in previous subsections.

- Most text in the intro part of section 6.9 (Proof of Source Address Validation) sounds like it should rather be in the security considerations section...

- Section 6.11.5 (Privacy Implications of Connection Migration) really seems to belong in the secuirty considerations instead.

- I would recommend to have section 6.12.4.2 (Calculating a Stateless Rest Token) before section 6.13.4.1 (Detecting a Stateless Reset).

- Depending on the final order I think there is some text in section 9 that belongs in section 7.20. I think in any case section 7.20 should also talk about the meaning of the last two bits. I would recommend to talk about the bit encoding only in section 7.20 and just introduce the concepts of bi/uni-direction and server/client-initiated in section 9.

- I would recommend to have the section on sending and receiving data (9.5) before the state diagrams are introduced.

- Order of section 10 (Flow Control) seemed completely random to me. 

Also not quite an issue on document structure directly, but definitely related and should probably be cleaned up together, is that there are a couple of duplicted normative statements, e.g.

sec 7.8. (MAX_STREAM_ID Frame)
"Loss or reordering can mean that a MAX_STREAM_ID frame can be
   received which states a lower stream limit than the client has
   previously received.  MAX_STREAM_ID frames which do not increase the
   maximum stream ID MUST be ignored."
sec 9.4 (Stream Concurrency)
"A receiver cannot renege on an advertisement; that is, once a
   receiver advertises a stream ID via a MAX_STREAM_ID frame,
   advertising a smaller maximum ID has no effect.  A sender MUST ignore
   any MAX_STREAM_ID frame that does not increase the maximum stream ID."
sec 10 (Flow Control)
"A receiver MAY advertise a larger offset at any point by sending
   MAX_DATA or MAX_STREAM_DATA frames.  A receiver cannot renege on an
   advertisement; that is, once a receiver advertises an offset,
   advertising a smaller offset has no effect.  A sender MUST therefore
   ignore any MAX_DATA or MAX_STREAM_DATA frames that do not increase
   flow control limits."

These normative statements do all say the same thing but are worded slightly different. To avoid any ambiguity, I would recommend to state these things normatively only once. There are a few more of these kind of cases... 

-- 
You are receiving this because you are subscribed to this thread.
Reply to this email directly or view it on GitHub:
https://github.com/quicwg/base-drafts/issues/411#issuecomment-413598713

---

From: Martin Thomson <[email-masked]>
Date: Thu, 16 Aug 2018 17:07:36 -0700

Thanks @mirjak.  @janaiyengar and I have some time set aside after the next interim meeting to look at this issue.  We've been waiting until the velocity of changes slows a little before attempting this because more changes tend to undo any work you do on improving structure and removing redundant text.  But it looks like things are stabilizing now.

-- 
You are receiving this because you are subscribed to this thread.
Reply to this email directly or view it on GitHub:
https://github.com/quicwg/base-drafts/issues/411#issuecomment-413720045