Hi Paul and Heather, Thank you for your replies! We have updated the document accordingly.
Please contact us with any further updates or with your approval of the document in its current form. We will await approval from each author prior to moving forward in the publication process. Updated XML file: https://www.rfc-editor.org/authors/rfc9720.xml Updated output files: https://www.rfc-editor.org/authors/rfc9720.txt https://www.rfc-editor.org/authors/rfc9720.pdf https://www.rfc-editor.org/authors/rfc9720.html Diff file showing all changes made during AUTH48: https://www.rfc-editor.org/authors/rfc9720-auth48diff.html Diff files showing all changes: https://www.rfc-editor.org/authors/rfc9720-diff.html https://www.rfc-editor.org/authors/rfc9720-rfcdiff.html (side-by-side diff) https://www.rfc-editor.org/authors/rfc9720-alt-diff.html (diff showing changes where text is moved or deleted) For the AUTH48 status of this document, please see: https://www.rfc-editor.org/auth48/rfc9720 Thank you, RFC Editor/rv > On Jan 15, 2025, at 9:58 AM, Heather Flanagan > <h...@sphericalcowconsulting.com> wrote: > > 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
