Re: Genart last call review of draft-ietf-httpbis-binary-message-04

Thanks Martin! This PR definitely improves comprehension, though I do think
a bit more could be done. But that’s up to you as editor obviously.

David


On Wed, May 25, 2022 at 09:13 Martin Thomson <mt@lowentropy.net> wrote:

> 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
>