Subject: [Gen-art] Genart last call review of draft-ietf-cbor-file-magic-11

From: Pete Resnick via Datatracker <[email-masked]>
Date: Fri, 15 Apr 2022 14:49:26 -0700

Reviewer: Pete Resnick
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-cbor-file-magic-11
Reviewer: Pete Resnick
Review Date: 2022-04-15
IETF LC End Date: 2022-04-15
IESG Telechat date: 2022-04-21

Summary: Some mostly nit/editorial comments that really should be taken care
of, but no showstoppers.

Major issues: None

Minor issues: None

Nits/editorial comments:

Section 1 could use a solid edit. Here are some editorial issues that stuck out
to me (as always, just suggested changes):

Paragraph 3 (this one is a content problem rather than strictly nits, but also
isn't a technical issue with the document):

OLD

                                 For instance, in classical MacOS, a
   resource fork was maintained that includes media type ("MIME type")
   information and therefore ideally never needs to know anything about
   the file.

NEW

                                 For instance, in classical MacOS, a
   resource fork was maintained separately from the file data that
   included file type information and therefore the OS ideally never
   needed to know anything about the file data contents to determine the
   media type.

No "But" is required at the beginning of paragraph 4.

Paragraph 5: Change "file" to "file contents". (For what it's worth, I disagree
with the paragraph, in that I think it's actually worse to keep the media type
information in the data portion of the file, but I don't have a problem with
you disagreeing with that in the introduction.)

Paragraph 8: Change the colon to a semicolon.

Paragraph 9: Replace "A third" with "An additional".

Swap paragraphs 9 & 10.

Paragraphs 13 & 14 seem confusing, if not contradictory.

Move paragraph 14 up after paragraph 8.

The last paragraph repeats the information in the 9th paragraph.

Section 2.1, last paragraph: Change "has already been allocated" to "is
described".

Appendix C, last paragraph before C.1: This is a repeat of the last paragraph
of section 2.3. I don't think it's necessary to repeat.