Tips and Resources for Authors
In addition to the guidance in the RFC Editor Style Guide (RFC 7322), we recommend taking the following steps:
- Start with a template so you can focus on the content.
- See the templates available from the I-D Author Resources site.
- Read your document out loud, then revise. Ask someone else to read it, then revise. Repeat. As you revise, keep in mind that clear, concise language is the goal.
- Review your document for common grammar and style issues. (Below, examples are preceded by “Ex:”.)
- Subject and verb agreement: If the subject is singular, then use a singular verb (and vice versa).
Ex: Using the mechanisms and procedures are important. (Incorrect.)
Using the mechanisms and procedures is important. (Correct; the subject is “using”.) - Misplaced modifiers: When a phrase modifies the wrong noun, see if you can rephrase.
Ex: It should accept the packet sent to the node that has an invalid value. (Incorrect.)
It should accept the packet that was sent to the node and has an invalid value. (Correct, assuming the intended meaning is that the packet, not the node, has the invalid value.) - Restrictive (that) and non-restrictive (which) clauses: The difference between restrictive and non-restrictive clauses is whether or not the information is “essential” to the meaning (and often the identity) of the noun it belongs to (CMOS 6.29).
- that (restrictive) – introduces information that is essential to the meaning of the sentence.
Ex: RST attacks that rely on brute force are relatively easy to detect at the TCP layer (i.e., only some RST attacks rely on brute force). - which (non-restrictive) – follows a comma and provides non-essential information.
Ex: RST attacks, which rely on brute force, are relatively easy to detect at the TCP layer (i.e., all RST attacks rely on brute force).
- that (restrictive) – introduces information that is essential to the meaning of the sentence.
- Ambiguous pronouns: Check for pronouns (e.g., “it”, “they”) that might be more clear as the noun to which it refers.
Ex: For each broadcast network, a designated router describes it in its network-LSA (Note: The “it” and “its” need clarification). - Abbreviations and apostrophes: Be careful of plural vs. possessive.
Ex: the LSRs (plural)
the LSR’s address (singular possessive)
the LSRs’ addresses (plural possessive) - Articles: definite (“the”) vs. indefinite (“a”/”an”) vs. none
This is a tricky aspect of the English language.
Ex: the router (definite: a specific router)
a router (indefinite: a non-specific router)
routers (no article: refers to “routers” in a general sense or all routers) - Terminology and notation
- Refer to existing RFCs on the topic.
Ex: This document uses the terminology defined in [RFC6275]. - Define terms or notations that are not well known.
Ex: “|” represents foo in this document. - A term should appear consistently throughout the document in terms of capitalization, hyphenation, spelling, etc., unless there is a specific reason.
Ex: white space vs. whitespace vs. ‘whitespace’ vs. Whitespace
- Refer to existing RFCs on the topic.
- Numbers: Use numerals when referring to bits, TLVs, specific values, etc. Use the spelled-out form when numbers are used in general text.
Ex: The field is set to 3.
Ex: There are five options.
- Subject and verb agreement: If the subject is singular, then use a singular verb (and vice versa).
- Keep a list of directives to provide to the RFC Editor once your document is approved for publication — for instance, if specific terms must appear in a certain way (spelling, hyphenation, capitalization, etc.), send us mail with your draft string in the subject line.
EFL Writing Resources
Britannica Dictionary: This dictionary gives more extensive use examples and explanations than typical dictionaries. This can be handy for phrasal verbs, count and noncount nouns, and participles. The site also includes a grammar Q&A log under the “Ask the Editor” tab.
The Online Writing Lab (OWL) at Purdue University: This page contains grammar and mechanics information.
A Practical English Grammar, Fourth Edition: This comprehensive reference guide allows easy index searching. It contains a number of helpful lists related to verb subcategorization, diagrams related to the verb use and sequence of tenses, and the ability to search by word or topic.
A.K. Thomson and A.V. Martinent, Oxford University Press 1960, 1969, 1980, 1986, ISBN: 0 19 431342 5 (paperback)
Other Writing Resources
“Richard Lanham’s Lard Factor and the Paramedic Method” for information on revising verbose text.