Hi all!
I agree with Paul's comments (though I admit I'm not as concerned about Section
# vs Sections #, #, #).
Heather Flanagan
Principal, Spherical Cow Consulting
h...@sphericalcowconsulting.com
sphericalcowconsulting.com
On Jan 14, 2025 at 6:17 PM -0800, Paul Hoffman <paul.hoff...@icann.org>, wrote:
> Thank you for the edit. In addition to your questions below, I have one
> notable editorial issue. The last paragraph of Section 1.1 used to say:
>
> Historical text from [RFC7990] such as Section 2 ("Problem
> Statement"), Section 4 ("Overview of the Decision-Making Process"),
> and Section 10 ("Transition Plan") were purposely omitted from this
> document. Text from [RFC7990] that repeated what was in other RFCs,
> particularly Section 8 (Figures and Artwork) and Section 9 (Content
> and Page Layout) were also removed.
>
> It now says:
>
> Historical text from [RFC7990], such as Sections 2 ("Problem
> Statement"), 4 ("Overview of the Decision-Making Process"), and 10
> ("Transition Plan"), was purposely omitted from this document. Text
> from [RFC7990] that repeated what was in other RFCs, particularly
> Sections 8 ("Figures and Artwork") and 9 ("Content and Page Layout"),
> was also removed.
>
> The fact that the titles break up the list of sections makes new text read
> quite badly; "10" is quite far away from "Sections". Please strongly consider
> keeping "... as Section 2 ("Problem Statement"), Section 4 ("Overview of the
> Decision-Making Process"), ..." The same would be true at the end of Section
> 1.2.
>
>
> > 1) <!-- [rfced] Please insert any keywords (beyond those that appear in
> > the title) for use on https://www.rfc-editor.org/search. -->
>
> There's not much to work with here, but the title is fine.
>
> > 2) <!-- [rfced] We wonder about trimming this sentence down for simplicity.
> >
> > Original:
> > [RFC7990] defined a framework for how RFCs would be published after
> > that document was published, including new formats and a new
> > "canonical format" for archiving RFCs.
> >
> > Perhaps A:
> > [RFC7990] defined a framework for how RFCs would be published.
> >
> > Or perhaps B:
> > [RFC7990] defined a framework for how RFCs would be published,
> > including new "publication formats" and a new "canonical format".
> > -->
>
> Option B is fine; I think A is too short on "how".
>
> > 3) <!-- [rfced] If no objections, we will use a definition list under
> > the first bullet in Section 1.1.
> >
> > Original:
> > * It defines four terms that replace the use of the term "canonical"
> > and clarifies "format":
> >
> > - The "definitive format", which is RFCXML
> >
> > - The "definitive version", which is a published RFC in the
> > definitive format
> >
> > - A "publication format", which is currently one of PDF, plain
> > text, or HTML
> >
> > - A "publication version", which is a published RFC in one of the
> > publication formats
> >
> > Perhaps:
> > * It defines four terms that replace the use of the term "canonical"
> > and clarifies "format":
> >
> > definitive format: RFCXML
> >
> > definitive version: a published RFC in the definitive format
> >
> > publication format: currently one of PDF, plain text, or HTML
> >
> > publication version: a published RFC in one of the publication formats
> > -->
>
> I like the bulleted list a little better, but I trust you on format here.
>
> > 4) <!-- [rfced] Does "to maintain a consistent presentation" apply
> > to all verbs (in which case, "published" seems odd)? Please review.
> >
> > Original:
> > 7.8. Consistency
> >
> > RFCs are copyedited, formatted, published, and may be reissued to
> > maintain a consistent presentation.
> >
> > Perhaps A (two sentences):
> > RFCs are copyedited, formatted, and then published. They may be
> > reissued to maintain a consistent presentation.
> >
> > Perhaps B (remove "published"):
> > RFCs are copyedited and formatted and may be reissued to maintain
> > a consistent presentation.
> > -->
>
> Given how hard we ground on this one idea in the WG, we did indeed muff it.
> Please use option A.
>
> > 5) <!-- [rfced] Should "updated policy" here be updated to "new policy"?
> >
> > Original:
> > Section 2.1 and Section 3 in this document are based on this updated
> > policy in [RFC9280].
> >
> > Perhaps:
> > Sections 2.1 and 3 in this document are based on this new
> > policy in [RFC9280].
> > -->
>
> Better yet, just remove "updated". It is "this policy in [RFC9280]".
>
> > 6) <!-- [rfced] Please review "following the guidance of the group of RFCs
> > described in [RFC7990]". Are any updates needed for clarity?
> >
> > Original:
> > The first RFC to be published following the guidance of the group of
> > RFCs described in [RFC7990] was [RFC8651], published in October 2019.
> >
> > Perhaps:
> > The first RFC to be published following the guidance
> > in [RFC7990] was [RFC8651], published in October 2019.
> > -->
>
> The guidance wasn't just 7990; it was the group of RFCs starting with 7990,
> so I would keep the current wording.
>
> > 7) <!-- [rfced] Is "publication formats" correct here? We ask because
> > Section 3
> > is titled "Publication Versions". Also, would it be helpful to include
> > references for the other RFCs that specify these?
> >
> > Original:
> > The publication formats are described in
> > Section 3 and fully specified in other RFCs.
> > -->
>
> Yow, we totally forgot that we removed all that stuff from Section 3. The
> sentence should read:
> The publication formats are fully specified in other RFCs.
>
> >
> > 8) <!-- [rfced] Please review "The definitive version...is the publication
> > version". Should this be updated as follows?
> >
> > Original:
> > The definitive version produced by the RPC is the publication version
> > that holds all the information intended for an RFC.
> >
> > Perhaps:
> > The definitive version produced by the RPC
> > holds all the information intended for an RFC.
> > -->
>
> Yes, that's clearer.
>
> > 9) <!-- [rfced] Should "HTML publication versions" be singular?
> >
> > Original:
> > That SVG will also appear in the HTML publication
> > versions.
> > -->
>
> Yes, singular.
>
>
> > 10) <!-- [rfced] To avoid personifying "updates" (updates consider,
> > take steps, limit), we suggest the following.
> >
> > Original:
> > Instead, it only
> > requires that such updates consider the potential for semantic
> > changes, take steps to understand the risk of a semantic change
> > (either deliberate or inadvertent), and to limit those risks.
> >
> > Original:
> > Instead, considering the potential for semantic
> > changes, taking steps to understand the risk of a semantic change
> > (either deliberate or inadvertent), and limiting associated risks
> > are the only requirements.
> > -->
>
> Yes, good.
>
> > 11) <!-- [rfced] Should "definitive versions" here be singular (i.e.,
> > "definitive version")?
> >
> > Original:
> > Allowing changes to the definitive versions and publication versions
> > of RFCs introduces risks.
> >
> > Perhaps:
> > Allowing changes to the definitive version and publication versions
> > of RFCs introduces risks.
> > -->
>
> Agree.
>
> > 12) <!-- [rfced] Would it be helpful to either add numbers or use two
> > sentences here to improve clarity?
> >
> > Original:
> > A significant risk is that unintended
> > changes could occur in either the definitive version or publication
> > versions of an RFC as a result of an editing error, or may be
> > introduced into a publication version when it is regenerated from the
> > definitive version.
> >
> > Perhaps (add numbers):
> > A significant risk is that unintended
> > changes could 1) occur in either the definitive version or publication
> > versions of an RFC as a result of an editing error or 2) be
> > introduced into a publication version when it is regenerated from the
> > definitive version.
> >
> > Or (split into two sentences):
> > A significant risk is that unintended
> > changes could occur in either the definitive version or publication
> > versions of an RFC as a result of an editing error. In addition, unintended
> > changes may be
> > introduced into a publication version when it is regenerated from the
> > definitive version.
> > -->
>
> I strongly prefer the latter (two sentences).
>
> > 13) <!-- [rfced] To improve clarity, may we update the text starting
> > with "and harm" as follows?
> >
> > Original:
> > This may result in the corruption of a standard,
> > practice, or critical piece of information about a protocol, and harm
> > to the reputation of the RFC series.
> >
> > Perhaps:
> > This may result in the corruption of a standard,
> > practice, or critical piece of information about a protocol, which may
> > harm the reputation of the RFC Series.
> > -->
>
> Sure.
>
> > 14) <!-- [rfced] Would you like to use a consistent ordering when referring
> > to the publication formats? We see the following (also note "text" and
> > "plain text"):
> >
> > HTML, text, and PDF
> >
> > PDF, plain text, or HTML
> >
> > HTML, PDF, and plain text
> > -->
>
> Consistency is good, but I would choose "HTML, plain text, and PDF". Adding
> "plain" to "text" is a good clarification.
>
> > 15) <!-- [rfced] Please review the "Inclusive Language" portion of the
> > online
> > Style Guide
> > <https://www.rfc-editor.org/styleguide/part2/*inclusive_language>
> > and let us know if any changes are needed. Updates of this nature typically
> > result in more precise language, which is helpful for readers.
> >
> > Note that our script did not flag any words in particular, but this should
> > still be reviewed as a best practice.
> > -->
>
> No changes needed here.
>
> --Paul Hoffman
>
--
auth48archive mailing list -- auth48archive@rfc-editor.org
To unsubscribe send an email to auth48archive-le...@rfc-editor.org
