[rfc-i] Call for Review of draft-iab-styleguide-01.txt, "RFC Style Guide"

Heather Flanagan (RFC Series Editor) rse at rfc-editor.org
Tue Mar 25 15:15:13 PDT 2014



On 3/11/14, 5:05 PM, Paul Hoffman wrote:
> 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...
> 
> --Paul Hoffman
> 
> 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.

I understand the concern that "web portion" sounds awkward, but I'm not
sure what you mean in the second half of the sentence.

> 
> In 2, "All RFCs begin as an Internet-Draft" is an unfortunate plural-singular mix.

Agreed.  Fixed.  "All RFCs begin as Internet-Drafts".

> 
> 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".

Agreed.  Fixed.

> 
> 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.
> 

Why would the items be called out later?  I don't think the fact that we
try to make sure RFCs are consistent internally, across clusters, and
across the Series is a question of style as much as it is part of our
overall purpose.  This section is to help set the understanding of what
we're trying to accomplish.

We left the items as a bulleted list to emphasize the distinctions and
order in which we check for consistency.

> In 2, The use of "prime directive" is cutely geeky, but maybe out of place.

Believe it or not, that didn't even register as a Star Trek reference to
me; the cute geekiness was not intended.

> 
> In 3.2, "block quotes" is not defined.

Do you think it's necessary?  Blockquote is a common term.  Or is the
concern that we do not have an example as we do with several other
points in that section?

> 
> 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".
> 

My understanding is that RFC 3986 and the W3C's URL spec both recommend
the use of angle brackets, but I am ok with the rewording.

> 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".
> 

That's not really accurate.  Perhaps the following is clearer?

"*  Titles of figures may be in sentence-style capitalization or may use
title case."


> 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.

These are not an errors, they are changes introduced to improve
readability and to keep people information together and easy to find.

> 
> In 4, "The elements preceding the body of the memo should not be 
> numbered" -> "are not numbered". Same for the text about back matter.
> 

The ordering and numbering of sections is strongly recommended, but this
guidance can be overridden if authors and stream approving bodies
request it.  "are not numbered" is more absolute than what is intended.

> 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.

Stream policy is interesting to capture, since depending on the stream,
it is either in an RFC, on a web page, or in case history.  I will make
the following change for author, with a similar change for contributor:

OLD
   The determination of who should be listed as an author or editor on
   an RFC is dependent on Stream policy.

NEW
   The determination of who should be listed as an author or editor on
   an RFC is made by the stream.

and capitalization will be normalized.

> 
> 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."

Added.

> 
> In 4.1.2, add "Individual Contributor" to the list of commonly-used affiliations.

Added.

> 
> In 4.3, the 20-line limit is a suggestion, and is not strictly enforced. For recent examples, see RFC 7087 and 7117.

How about:
NEW:
Every RFC must have an Abstract that provides a concise and
comprehensive overview of the purpose and contents of the entire
document, to give a technically knowledgeable reader a general overview
of the function of the document.
> 
> In 4.7, including a table of contents is a suggestion, and is not strictly enforced. For a recent example, see RFC 7154.

The rule today is that a TOC is only required for RFCs longer than 30
pages and recommended for RFCs longer than 15 pages.  I am changing this
to be required for all RFCs.

> 
> 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."

OK.  Changed.

> 
> In 4.8.6.1, 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.

Web caching services still exist.  Do they have a different name now?

I also don't have a better term for personal space - do you have any
suggestions?

Regarding the overall guidance, something needs to go here to indicate
what the editors will question.  Editors have no way of determining if
www.university.edu/~joe is a tenured faculty at an institution that will
never delete his web directory, or an adjunct faculty whose web space
may disappear along with his grant without a great deal of work.  And
while I think we are likely going to have to accept most of the web page
references that come in as informative references, normative references
must be as stable and reputable as possible given the fluctuations of
the web world.

So, what that means for the text is: I am open to clarifying the
existing text, but not to removing it entirely.  Some proposed
alternative text:


The use of URIs in references is acceptable as long as the URI is the
most stable (i.e., unlikely to change and expected to be continuously
available) and direct reference possible.  The URI will be verified as
valid during the RFC editorial process.  Personal web pages and web
caching services are not considered stable and will not be accepted as
normative references.  Informative references to personal web pages
(including blogs) are discouraged, but are acceptable if they are deemed
the most stable reference available.

> 
> In 4.8.6.1, the paragraph about DNS names needs to be moved to a different section, since these do not appear in references.

I see your point and will talk to Sandy about this.

> 
> In 7.2, the reference for [BC18] and [RFC1311] should have URLs.

Fixed.

> 
> In 7.2, the URL for [IDGuide] is not sufficient.
> 

Fixed.

> In 7.2, the reference to [ISO3166] should have the full attribution for the ISO committee.

Actually, there is more wrong with that reference now that I look at it.
 The citation tag has been changed to [ISO_OBP] and the reference to

   [ISO_OBP]  ISO, "Online Browsing Platform",
              <https://www.iso.org/obp/ui/>.


> 
> General: The document use two styles for non-RFC references: all-caps and camel-case. Pick one.

Where we can and it seems reasonable, we try to respect the citation
recommendations of other SDOs.  That introduces some variability in the
citations.  But we will go through the references again to make sure
it's as it should be.

In general, this new style guide is not about documenting current
practice, though there is certainly a large overlap in current practice
and what Sandy and I have captured here.  This guide is about
establishing the rules and recommendations for the style we intend to
apply going forward.

Thank you for reviewing the draft!
Heather


More information about the rfc-interest mailing list