Hey David, I blame laziness for not trying this earlier, but once I tried out something *like* your suggestion I found I was pleased.
https://github.com/httpwg/http-extensions/pull/2127 It might not be as much of a change as you imagined, but I think that a small change like this does improve comprehension somewhat. Thanks, Martin On Tue, May 24, 2022, at 23:59, David Schinazi via Datatracker wrote: > Reviewer: David Schinazi > Review result: Ready with Issues > > 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 _______________________________________________ Gen-art mailing list Gen-art@ietf.org https://www.ietf.org/mailman/listinfo/gen-art
