Internet-Draft Effective Terminology August 2020
Gondwana Expires 26 February 2021 [Page]
Intended Status:
Standards Track
B. Gondwana, Ed.

Effective Terminology in IETF drafts


The IETF and the RFC series are trusted names, for producing high quality technical documents that make the Internet work better.

While the success of our documents is variable, many of them are widely used over a long time period.

As norms in the outside world change, our documents need to remain relevant and accessible to future generations of those working on the internet, everywhere in the world.

This longevity of our documents, and the impossibility of predicting the future, implies that we should be conservative in the language that we send. Effective language expresses our intent with clarity, and without distraction.

This document describes a glossary for increasing awareness of terms which are going to be clear and effective without turning readers away, to enable our mission of making the Internet work better.

Status of This Memo

This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.

Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at

Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."

This Internet-Draft will expire on 26 February 2021.

Table of Contents

1. Introduction

The IETF, and even more so the three magic letters "RFC", is a valuable brand. This brand is valuable because we have produced many documents over the past 50 years which have helped others interoperate, and have kept the decentralized internet reliable. This is an amazing success, and a clear sign that we are doing a lot of things right.

The IETF has no coercive power in the world, our documents are adopted because of their quality and our reputation. The documents stand on their merits, and we create change in the world through persuasion and trust.

This is a large responsibility. We are keen to bring the benefits of our work to as many people as possible, and to be ethical in assessing our impact on the world (see [I-D.draft-iab-for-the-users]).

In the same way that "Security Considerations" in every document detail how we imagine our work can be misused, we also need to consider ways in which our work can harm or exclude.

2. Adapting to a changing world

2.1. Words have multiple meanings and change meanings over time

While a word can have one meaning a technical context, it can have other meanings which are highly distracting to the reader. A topical example from 2020 is the word "Trump". In many card games, any trump card always defeats every non-trump card which is played in the same round. This idea is a very useful metaphor for any overriding consideration that must take priority, but it is also the surname of the 45th President of the United States of America, and many readers will be distracted from the technical purpose of the document upon seeing this word.

Likewise, words have different meanings in different cultures, different languages, or to different groups of humans.

While we can't enumerate all possible words which are distracting, we can avoid the ones we know. This naturally happens anyway as individuals in working groups become aware of them, and it happens more quickly if we crowd-source change.

2.2. Words can encourage or discourage participation

It is human nature to look for encouraging or discouraging signals when interacting with any group, particularly at the start. We look for signals to see whether we are welcome, and whether we will be treated fairly. While we can't predict how everybody will react, there are broad strokes where sending a signal can encourage participation.

Our documents are effective when the rest of the world trusts us to produce quality work, and wants to use that output. If we use words that turn people away who are writing standards, they will do their work elsewhere. If we use words that turn people away who are reading standards, they will bypass us and look for standards elsewhere.

We remain relevant by being persuasive and welcoming to the largest possible audience. "Virtue Signalling" has a dirty name, but "welcome signalling" is valuable to the extent that we follow up by actually welcoming new people and being a place where they want to participate. Thoughtful choice of words to use is part of being welcoming.

A diversity of new people with different backgrounds contributing to the IETF brings new ideas and new knowledge, and is valuable when their contributions are technically sound and in line with our mission.

2.3. Analogies change meaning over time

In the year 2020, the icon for "save" is still an image of a floppy disk, though there are more software users every year who have never actually used a floppy disk.

Generally, changes in meaning will come from outside the IETF, and be organically taken up by authors who are building documents that they hope will last.

2.4. The best time to plant a tree is 20 years ago

The full proverb is "the best time to plant a tree is 20 years ago, the second best time is now". While it is costly to change terminology, or to replace an existing protocol, it will only be more costly in the future!

This analogy does not always hold. We can't do all possible work at the same time, so just because something has some value does not mean that it's the most valuable use of our time.

However, just because something will take a long time or be costly does not mean that delaying it or not doing it is a better choice.

3. Change is not always necessary

3.1. What we're doing is generally working

It is easy to criticize various parts of how the IETF functions - nobody thinks we're perfect in every way - however we are achieving our mission quite well. It's important to stay grounded in that reality and acknowledge that while we may be able to do better in certain ways, what we have right now is pretty great.

3.2. We will naturally follow emerging consensus in the wider world

When a technical word happens to match a word which is harmful in other contexts, it does not always turn away a significant population who would otherwise both engage with, and add value to, our community.

Where a consensus is developing in the wider world about a term, it will follow that reviewers, both inside working groups and during last call, will notice those terms and flag them as possible concerns to the authors.

4. How to choose terminology for our documents

4.1. Engineering considerations take priority

Sound engineering judgement and compatibility with deployed systems are primary values that serve us well. They are why our documents are well regarded and continue to have value.

Solving difficult problems can be uncomfortable. While we don't want to deliberately make people uncomfortable, correctness must be a more important value than keeping everybody comfortable, to retain the quality of our work. We must embrace conflict to be able to solve difficult problems, while ensuring that we debate the technical issues, not the person raising them.

Our documents are the bedrock of the internet. While fashions change in tech quite quickly, we should strive to be as timeless as possible with our designs, so that we don't need to revise our work frequently.

4.2. Avoidance of "pixie dust"

Technical terms are often chosen based on analogies from civilian life.

No analogy is 100% perfect. There are always tradeoffs with novelty, searchability, accessibility and confusion potential.

Where an existing term adequately describes a concept, it is preferable to use that term. If there are multiple terms for the same thing, the best choice is one least likely to cause confusion.

4.3. Decentralised control

Those closest to the document are best placed to know which terms are in wide use within their own fields, and will be best understood.

The work is done by those who show up.

It is incumbent on the authors to treat feedback on terminology from the working group, and from other reviewers, in the same way they treat technical feedback - soliciting advice and making choices in the best interests of the IETF, the Internet, and the long-term success of their document.

It is incumbent for those reviewing and wishing to provide feedback to understand the scope and history of any technical term, and not just match on keywords and provide no other contribution.

Final term choice always rests with document authors. The mechanisms for objecting to that are the same as for technical choices - a competing draft with different authors, or failure to form consensus and progress the document.

4.4. Centralised knowledge

The entire IETF is best placed to have an overview of which terms have different meanings in other contexts and may generate unwanted side effects.

It would be valuable for a group within the IETF to maintain a glossary of terms, with both their technical meanings and other meanings in different cultures, professions, or languages.

This document should reference other similar documents produced by non-IETF groups, in order to align our language with the rest of the world.

This resource would be useful for authors and working groups - both for words to avoid when coining new technical terms, as well as to avoid creating multiple terms with the same meaning.

5. IANA Considerations

This document does not ask the IANA to do anything (unless we decide that IANA is a good place for a central glossary to be kept)

6. Security Considerations

Bad faith actors can already interrupt the consensus process by raising spurious and unsubstantiated complaints that look reasonable at first glance.

To the extent that claims of harmful terminology are harder to prove or evaluate than other claims, this makes it easier to derail the IETF from its mission, and to use the IETF's brand as clout in political battles.

Working Group Chairs and the IESG should be wary of changes to terminology requested by those with no relationship to the work being done or interest in evaluating the tradeoffs being made.

7. Changes

EDITOR: please remove this section before publication.

The source of this document exists on github at:

draft-gondwana-effective-terminology-00 - my initial suggestions, probably needs lots of review and I imagine I've missed a lot. Please give kind feedback!

draft-gondwana-effective-terminology-01 - based on initial private feedback, trimmed the "Background" section entirely and simplified some wording.

8. Acknowledgements

Author's Address

Bron Gondwana (editor)
Level 2, 114 William St
Melbourne VIC 3000