Web Portion of the Style Guide

The following style issues have been raised with the RFC Editor. The RFC Editor has discussed these issues and intends to address them as described below. These may become part of the greater Style Guide when it is revised. As new recommendations are being tested or updated to reflect current usage, this site will change.

MUSTs

The RFC Editor requires the following conventions when writing a document. Updates will be made to text to follow these guidelines during the editing process. The RFC Editor appreciates compliance in submitted drafts.

Topic Requirement
RFCs as Compounds Whenever possible:

  • Hyphenated compounds formed with RFC numbers should be avoided; 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.).

If use of an RFC number in attributive position is unavoidable, the preferred form should appear as in the example “RFC 5011-style rollover”.  That is:

  • no hyphen between “RFC” and the number (don’t use RFC-5011-style rollover)
  • avoid hyphenating citations with text (don’t use [RFC5011]-style rollover)

*Note that occurrences using the RFC number as part of a hyphenated compound may be questioned at AUTH48.
Referencing RFCs The DOI is listed in each reference to an RFC. This implies various updates in Section 4.8.6.2 (“Referencing RFCs”) of RFC 7322. The first example 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 As of 4 May 2017, unique and stable URIs are available for each erratum. As such, the format for errata references is being updated to include these URIs. The new format is 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 RSE’s announcement on the RFC interest list.

Referencing Web-Based Public Code Repositories (e.g., GitHub)
  • Should not appear as Normative References.
  • 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/>.
Index Placement If included, an index appears directly after any appendices and before the Acknowledgements (if any). Where applicable, it appears before the “IAB Members at the Time of Approval” section. This is an update to RFC 7322.

RECOMMENDED

The RFC Editor recommends the following practices, but will not enforce the guidelines below if the author has chosen a different style.

Note that the RFC Editor will ask questions if the text is unclear.

Topic Recommendation
Length of Sections All RFCs are naturally divided in to sections. We recommend that the length of a section or subsection be limited to allow for easily referenced objects.
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 Abbreviations should be expanded upon first use. The abbreviated form should be used thereafter.
Didactic Capitalization Use of didactic capitalization is not needed. For example:

Extensible Markup Language (XML) (not EXtensible Markup Language (XML)
             or eXtensible Markup Language (XML))
In-text Citations (bracketed citation) An in-text citation may a) follow the subject for which it is being cited 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.
Referring to specific sections within another document This is mostly left to author preference. However, note the following:

  • Instances of “[RFCXXXX] section N.N” will be updated as “[RFCXXXX], Section N.N” in most cases.
  • If that format may be unclear, the text will be updated as “Section N.N of [RFCXXXX]”.
  • If neither option works for some reason, a question will be sent to the authors.
References to IEEE documents Per the IEEE coordination team, listing dates for IEEE standards is not recommended unless there is a need to cite a particular section, in which case the dated reference is appropriate. An RFC with a dated IEEE reference suggests that the RFC only applies to that specific IEEE specification.
Referencing Email on Mailing Lists When referencing emails to mailing lists, the template provided here should be used:

  
[reftag] Sender, A., "Subject: Subject line", message to the 
listname mailing list, DD Month YYYY, <URL>.

See the template here: reference template.
URIs HTTPS URIs should be used when possible.
Gender-Specific Language Avoid using gender-specific language (e.g., “his” and “her”) when possible. Consider whether gender-neutral terms could be used instead (e.g., “the user”, “its”, and “their”).

Authors’ Choice

The RFC Editor leaves the following issues to the authors’ discretion, unless the text is unclear.

Topic Description
RFC 2119 Keywords in Quoted Text A reference is not required if the keywords are only used in quoted text. However, a reference may be included.
Double Negatives Double negatives are discouraged but are allowed.
Terminology Sections Terminology sections are recommended for docs that are terminology/abbreviation heavy, but documents should point to existing definitions when possible.

Last updated 14 December 2017.


Advanced Search