Approved on my side. Thanks for all your work on it! Heather Flanagan Principal, Spherical Cow Consulting h...@sphericalcowconsulting.com sphericalcowconsulting.com
On Jan 15, 2025 at 11:00 AM -0800, Rebecca VanRheenen <rvanrhee...@staff.rfc-editor.org>, wrote: > 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
