Last Call Review of draft-ietf-httpbis-binary-message-04
review-ietf-httpbis-binary-message-04-genart-lc-schinazi-2022-05-24-00

I am the assigned Gen-ART reviewer for this draft. The General Area
Review Team (Gen-ART) reviews all IETF documents being processed
by the IESG for the IETF Chair.  Please treat these comments just
like any other last call comments.
For more information, please see the FAQ at
<https://trac.ietf.org/trac/gen/wiki/GenArtfaq>.

Document: draft-ietf-httpbis-binary-message-04
Reviewer: David Schinazi
Review Date: 2022-05-24
IETF LC End Date: 2022-06-03
IESG Telechat date: Not scheduled for a telechat

Summary: Well written concise draft, apart from section 3 - see below.

Major issues: None

Minor issues: While this is an editorial comment, I'm raising it as a minor
issue because it significantly hampers comprehension in my mind. I find Section
3 incredibly hard to reason about. In order to get to the actual format, the
reader is forced to repeatedly jump forward and backwards using a notepad to
track state. The draft seems somewhat akin to a game like Myst if you'll pardon
the analogy. I believe that this could be resolved by the editors without too
much work by doing the following: - keep the preface to Section 3 as-is, it
does a great job of introducing the concepts - split up the "Message with
Known-Length" diagram into two diagrams, one for known-length request and one
for known-length response - similarly split up "Indeterminate-Length Message"
diagram - reorder diagrams to avoid forward references, for example
"Known-Length Field Section" should appear before "Message with Known-Length"
since the latter relies on the former - define every field using a separate
bullet following the style from RFC 9000. Currently the draft uses the
notational conventions from RFC 9000 albeit incorrectly, for example
"Known-Length Informational Response" does not appear in all "Message with
Known-Length" structs but the square brackets indicating optionality are
missing.

While this is fundamentally an editorial issue that is theoretically the
purview of the editors, such readability difficulties are worth discussing by
the GEN Area Director if they agree with this assessment.

Nits/editorial comments: None