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:
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:
*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 IANA Registries | The following form should be used to reference an IANA registry (including a specific entry within the registry). Per IANA’s preference, the URL included in the reference should be to the top-level registry.
[NAME] IANA, "Registry Name", <url>. Example: [IANA-IKE] IANA, "Internet Key Exchange (IKE) Attributes", <http://www.iana.org/assignments/ipsec-registry>. |
Referencing Internet-Drafts | References to Internet-Drafts will list the series as Internet-Draft, will include the day of publication for the version referenced, and will include a URL to the HTML file (with no file extension). For example:
[RFC7322bis] Flanagan, H. and S. Ginoza, "RFC Style Guide", Work in Progress, Internet-Draft, draft-flanagan-7322bis-03, 3 April 2018, <https://tools.ietf.org/html/draft-flanagan-7322bis-03>. |
Referencing Web-Based Public Code Repositories (e.g., GitHub) |
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:
|
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 26 September 2019.