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 -- [email protected]
To unsubscribe send an email to [email protected]
