Explain format more

[larseggert]

The layout of a Version Negotiation packet is:

Version Negotiation Packet {
Header Form (1) = 1,
Unused (7),
Version (32) = 0,
Destination Connection ID Length (8),
Destination Connection ID (0..2040),
Source Connection ID Length (8),
Source Connection ID (0..2040),
Supported Version (32) ...,
}

             Figure 14: Version Negotiation Packet

The value in the Unused field is selected randomly by the server.

When I first met this text the following questions arose.
What does the (7) in unused mean?
What length is Destination/Source Connection ID/What does (0..2040) mean?
Now I have figured this out, but I really worry about how difficult this is
for the new/casual reader of the text.

[MikeBishop]

The notation is described in Section 1.3, before it is ever used in the document. It seems excessive to refer back to the diagram conventions from every diagram. I'm not sure what would make this clearer for a reader who doesn't read the introduction.

[janaiyengar]

This might be difficult for a casual reader of the text, but I would argue that we shouldn't optimize for them. As Mike notes, there are a large number of diagrams, and the notations section exists precisely to capture common notation that is used throughout the document.

[StewartBryant]

I think perhaps a small tutorial section somewhere, either in the beginning or forward referenced to an appendix would help.

Remember other target audiences are people who are used to conventional definitions of transport protocols some of whom need to operate the network and some of whom only need to know enough to design adjacent layers (for example the routing engineers).

[MikeBishop]

Can you suggest what you'd expect to see in such a tutorial beyond what exists in Section 1.3?

[janaiyengar]

What @MikeBishop asks.

@StewartBryant : Other target audiences still ought to be careful readers of the document. I hope that those who operate the network don't do it with a casual reading of protocol documents.

[janaiyengar]

I'm marking this as proposal-ready. We can switch it back if we decide to do something here.

[LPardue]

The proposed resolution was to close to with action, which was signalled to the appropriate review channel.

Hearing no pushback, I'm closing this.