Web Portion of the Style Guide

The following style issues have been raised with the RFC Production Center since RFC 7322, “RFC Style Guide”, has been published. These will be considered for the greater Style Guide when it is revised. Note that a revision draft is in GitHub. This page will be updated to reflect current usage.

Note that the RFC Production Center follows these guidelines but will edit and ask questions as needed.

MUSTs

The following conventions are required in RFCs. Updates will be made to text to follow these guidelines during the editing process. We appreciate compliance in submitted drafts.

Topic Requirement
Referencing RFCs The Digital Object Identifier (DOI) is now listed in each reference to an RFC. The first example in Section 4.8.6.2 (“Referencing RFCs”) of RFC 7322 is updated as follows.
For one author or editor:

[RFCXXXX] Last name, First initial., Ed. (if applicable), “RFC Title”, Sub-series number (if applicable), RFC number, DOI, Date of publication, <https://www.rfc-editor.org/info/rfc#>.

Example:
[RFC3080] Rose, M., “The Blocks Extensible Exchange Protocol Core”, RFC 3080, DOI 10.17487/RFC3080, March 2001, <https://www.rfc-editor.org/info/rfc3080>.
Referencing Errata The format for errata references described in Section 4.8.6.5 of RFC 7322 is updated as follows:
[ErrNumber] RFC Errata, Erratum ID number, RFC number, <URI>.

Example:
[Err3607] RFC Errata, Erratum ID 3607, RFC 4627, <https://www.rfc-editor.org/errata/eid3607>.

For more details, see the announcement on the RFC interest list.
Referencing IANA Registries Use the following form to reference IANA registries. Note that the top-level URL is used when referring to a group of registries and/or specific registries within the group.

[NAME] IANA, “Registry Group or Registry Name”, <URL>.

Example for a registry group:
[IANA-ANCP] IANA, “Access Node Control Protocol (ANCP)”, <https://www.iana.org/assignments/ancp>.

Example for a specific registry within the group:
[IANA] IANA, “ANCP Message Types”, <https://www.iana.org/assignments/ancp>.

Note: This guidance was developed in coordination with IANA.
Referencing Internet-Drafts A reference to an Internet-Draft has been updated (from Section 4.8.6.4 of RFC 7322) to include the day of posting (in addition to the month and year), the word “Internet-Draft”, and the URL of the HTML file.

Example:
[RFC7322bis] Levine, J., Ed., and S. Ginoza, “RFC Style Guide”, Work in Progress, Internet-Draft, draft-flanagan-7322bis-07, 7 April 2021, <https://datatracker.ietf.org/doc/html/draft-flanagan-7322bis-07>.
Referencing Web-Based Public Code Repositories (e.g., GitHub) Used for Informative References only.

Format of reference entries:

  • authors — omit them
  • title — include if available (some judgement may be required on the part of the editors and authors to have a sensible title)
  • commit hash — include if exists, short form preferred if available
  • date — use date of last commit at time doc is edited
  • URL — include URL to main page of repository

Examples:
[pysaml2] “Python implementation of SAML2”, commit 7135d53, March 2018, <https://github.com/IdentityPython/pysaml2>.

[linuxlite] “Linux Lite”, March 2018, <https://sourceforge.net/projects/linuxlite/>.
Referencing Email on Mailing Lists When referencing emails to mailing lists, use the following template:

[reftag] Sender, A., “Subject: Subject line”, message to the
listname mailing list, DD Month YYYY, .
Index Placement If included, an index appears directly before the Authors’ Addresses Section.

RECOMMENDED

The following practices are recommended. Updates may be made to text to follow these guidelines during the editing process.

Topic Recommendation
Inclusive Language Because each stream has chosen to follow the IESG statement on Inclusive Language, the RFC Editor encourages authors to apply the guidance described in “Guidance for NIST Staff on Using Inclusive Language in Documentary Standards”. See Table 1 on the NIST website for an expanded list of potentially biased language along with possible substitutions.
Double Negatives Double negatives are discouraged.
RFCs as Compounds Avoid forming compounds by hyphenating RFC numbers; this can be accomplished by

  • rewording the sentence (e.g., “[RFC5011]-style rollover” –> “rollover as described in RFC 5011”).
  • adding a note in either the Terminology or Conventions section mentioning the RFC so that other occurrences throughout the text will be understood by the reader to be in the style of said RFC (e.g., “This document uses the term “rollover” as defined in RFC 5011”).
Abbreviations as Verbs Avoid using abbreviations as verbs when possible. If unavoidable, suffixes should be affixed without punctuation, for example, “XORed” (not XOR’ed) and “NATed” (not NAT-ed).
Expanding Abbreviations upon First Use Once an abbreviation has been introduced, the abbreviated form should be used thereafter.
In-text Citations (bracketed citation) An in-text citation may a) follow the subject for which it is being cited as a silent pointer to the referenced document or b) be read as part of the text.

For example:

a) As part of the transition to IPv6, NAT64 [RFC6146] and DNS64 [RFC6147] technologies will be utilized by some access networks to provide IPv4 connectivity for IPv6-only nodes [RFC6144].

or

b) Note that SAVI raises a number of important privacy considerations that are discussed more fully in [RFC6959].

We recommend using a) and strongly recommend consistent use of one style throughout.
URIs HTTPS URIs should be used when possible.

Author Choice

The following items are left to the authors’ discretion.

Topic Description
RFC 2119 Keywords in Quoted Text A reference is not required if the keywords are only used in quoted text.
Terms You may format terms as you see fit by using capitalization, quotation marks, emphasis, etc. However, consistency within the document and within the Series is strongly recommended.
Please provide any style guidance to the RFC Production Center when your document enters the queue.
Terminology Sections Terminology sections are recommended for docs that are terminology/abbreviation heavy, but documents should point to existing definitions when possible.
Didactic Capitalization Use of didactic capitalization is not needed.
Example: Extensible Markup Language (XML)
(not EXtensible Markup Language (XML) or eXtensible Markup Language (XML))
Length of Sections We suggest that the length of a section or subsection be limited to allow for easily referenced objects.

Last updated 1 August 2022.


Advanced Search