[rfc-i] Call for Review of draft-iab-styleguide-01.txt, "RFC Style Guide"
paul.hoffman at vpnc.org
Tue Mar 11 17:05:09 PDT 2014
It would be nice to come to (probably temporary completion) of the Style Guide. The following are comments on the -01 draft. There is a much larger issue that I am opening in a different thread. Also, some of the comments below indicate topics that might need to spawn their own threads; let's see how well people do that...
In 1, The term "web portion" sounds weird, and having the web extension of the style guide be referred to as a reference instead of an actual URL feels stilted.
In 2, "All RFCs begin as an Internet-Draft" is an unfortunate plural-singular mix.
In 2, "Look for larger content/clarity issues" and "Point out inconsistencies" are not goals, they are mechanisms. The goals are "Correct larger content/clarity issues" and "Fix inconsistencies".
In 2, The list that is preceded by "We strive for consistency within" seems weird because the items are not later called out. That whole thing would be more readable as a a sentence.
In 2, The use of "prime directive" is cutely geeky, but maybe out of place.
In 3.2, "block quotes" is not defined.
In 3.2, the rule for angle brackets around URIs is over-broad and could be dangerous. It should be changed to "Angle brackets are strongly recommended around URIs that are used as external references".
In 3.3, "Titles of figures may be in sentence form or use title case" is unclear. It sounds like figure titles have to end in a period, which does not seem to be true. A better wording would be "Figure titles normally use title case, but might instead use only an initial capital for the first word".
In 4, the order has an error. In the large majority of recent RFCs, the acknowledgements and contributors sections come before the references, not as appendices. Further, in some recent RFCs, even when they are after the references, they are numbered sections, not appendices. Given this, Sections 4.10 and 4.11 are also misplaced.
In 4, "The elements preceding the body of the memo should not be numbered" -> "are not numbered". Same for the text about back matter.
In 4.1.1, "Stream policy" seems weird. It should be introduced and described much earlier in the document. Also, the capitalization of "stream" needs to be examined; later in the same section, "stream manager" is used.
In 4.1.1, the second paragraph needs to say what happens for authors who have non-ASCII characters in their name. Proposal: "Authors' names that cannot be represented in ASCII are first Romanized, then normalized to be ASCII-only. This rule is likely to change in the future."
In 4.1.2, add "Individual Contributor" to the list of commonly-used affiliations.
In 4.3, the 20-line limit is a suggestion, and is not strictly enforced. For recent examples, see RFC 7087 and 7117.
In 4.7, including a table of contents is a suggestion, and is not strictly enforced. For a recent example, see RFC 7154.
In 4.8.6, it says "It is acceptable for an obsoleted document to be listed as long as the most recent document is referenced also." That's not completely true, because a document that is obsoleting another document can refer to the older one. Proposed change: "When referring to an obsoleted document, it is common practice to also refer to the most recent version as well."
In 22.214.171.124, use of "web caching services" is archaic. Also, "personal space" sounds quite touchy-feely. It is also inappropriate: in the security field, many vulnerabilities are described only on personal blogs, not organizational blogs or academic papers.
In 126.96.36.199, the paragraph about DNS names needs to be moved to a different section, since these do not appear in references.
In 7.2, the reference for [BC18] and [RFC1311] should have URLs.
In 7.2, the URL for [IDGuide] is not sufficient.
In 7.2, the reference to [ISO3166] should have the full attribution for the ISO committee.
General: The document use two styles for non-RFC references: all-caps and camel-case. Pick one.
More information about the rfc-interest