Effective Terminology in IETF drafts
draft-gondwana-effective-terminology-00
The information below is for an old version of the document.
| Document | Type | Active Internet-Draft (individual) | |
|---|---|---|---|
| Author | Bron Gondwana | ||
| Last updated | 2020-08-25 | ||
| Stream | (None) | ||
| Formats | plain text html xml htmlized pdfized bibtex | ||
| Stream | Stream state | (No stream defined) | |
| Consensus boilerplate | Unknown | ||
| RFC Editor Note | (None) | ||
| IESG | IESG state | I-D Exists | |
| Telechat date | (None) | ||
| Responsible AD | (None) | ||
| Send notices to | (None) |
draft-gondwana-effective-terminology-00
GENDISPATCH B. Gondwana, Ed.
Internet-Draft Fastmail
Intended status: Standards Track 23 August 2020
Expires: 24 February 2021
Effective Terminology in IETF drafts
draft-gondwana-effective-terminology-00
Abstract
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 mechanism for increasing awareness of words
that are likely to cause distraction to readers, both now and in the
future, while maintaining document clarity and not interfering with
our mission.
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 https://datatracker.ietf.org/drafts/current/.
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 24 February 2021.
Gondwana Expires 24 February 2021 [Page 1]
Internet-Draft Effective Terminology August 2020
Copyright Notice
Copyright (c) 2020 IETF Trust and the persons identified as the
document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents (https://trustee.ietf.org/
license-info) in effect on the date of publication of this document.
Please review these documents carefully, as they describe your rights
and restrictions with respect to this document. Code Components
extracted from this document must include Simplified BSD License text
as described in Section 4.e of the Trust Legal Provisions and are
provided without warranty as described in the Simplified BSD License.
Table of Contents
1. Background . . . . . . . . . . . . . . . . . . . . . . . . . 2
2. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
3. Adapting to a changing world . . . . . . . . . . . . . . . . 4
3.1. Words have multiple meanings and change meanings over
time . . . . . . . . . . . . . . . . . . . . . . . . . . 4
3.2. Words can encourage or discourage participation . . . . . 4
3.3. Analogies change meaning over time . . . . . . . . . . . 5
3.4. The best time to plant a tree is 20 years ago . . . . . . 5
4. Change is not always necessary . . . . . . . . . . . . . . . 5
4.1. What we're doing is generally working . . . . . . . . . . 5
4.2. There is not consensus in the wider community on words
causing harm . . . . . . . . . . . . . . . . . . . . . . 6
5. How to choose terminology for our documents . . . . . . . . . 6
5.1. Engineering considerations take priority . . . . . . . . 6
5.2. Avoidance of "pixie dust" . . . . . . . . . . . . . . . . 6
5.3. Decentralised control . . . . . . . . . . . . . . . . . . 7
5.4. Centralised knowledge . . . . . . . . . . . . . . . . . . 7
6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 7
7. Security Considerations . . . . . . . . . . . . . . . . . . . 8
8. Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
8.1. draft-gondwana-effective-terminology-00 . . . . . . . . . 8
9. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 8
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 8
1. Background
There has been much debate about the use of terminology in IETF
documents in 2020, and the debate has focused on the areas in which
we disagree.
There's a lot we do agree on.
Gondwana Expires 24 February 2021 [Page 2]
Internet-Draft Effective Terminology August 2020
There are policy suggestions that we don't agree on, either because
we hold different values, or we hold the same values with different
weight.
There are also a subset of the facts that we don't agree on, and
likely will never agree on. We disagree on the costs of proposed
changes, and we disagree on the benefits. You can't do a cost/
benefit analysis without agreeing on both of those, so we can't form
a consensus which relies on a cost/benefit tradeoff in those areas.
There is a suspicion among some participants in the IETF that our
institutional power is being leveraged to add weight to the idea that
consensus already exists in the world that certain words are
inherently causing damage - and anyone who disagrees is in the rough.
Within the IETF we do not have consensus on whether simply removing
certain words will increase or decrease the quality of participation
in the IETF, or the influence that our documents have in the world.
It is not simple to change existing standards or change terminology
for existing concepts. It's not just search/replace once, the
synonymous terms will travel in parallel for a long time, causing
confusion and fragility in systems (hopefully rarely at the level of
crashing space probes because of incorrect units!)
The IETF works by rough consensus. Possible pathways to consensus
are persuasion, fatigue, or declaring the opposition to be in the
rough! Of these, persuasion is by far the preferable.
This document is an attempt to highlight the bits where we do agree,
persuade both "sides" that the other side has valid points, and find
a path forward.
2. 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.
Gondwana Expires 24 February 2021 [Page 3]
Internet-Draft Effective Terminology August 2020
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.
3. Adapting to a changing world
3.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.
3.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.
Gondwana Expires 24 February 2021 [Page 4]
Internet-Draft Effective Terminology August 2020
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.
3.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.
3.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.
4. Change is not always necessary
4.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.
Gondwana Expires 24 February 2021 [Page 5]
Internet-Draft Effective Terminology August 2020
4.2. There is not consensus in the wider community on words causing
harm
When a technical word happens to match a word which is harmful in
other contexts, it is widely disputed that continuing to use such
words turns away a significant population who would otherwise both
engage with, and add value to, our community.
It is likewise disputed that the existence of those terms in our
documents discourages their use, or causes harm to those who come
across them.
In the case of words where wide agreement does exist, there's a
natural tendency among authors and working group members to avoid
those words.
5. How to choose terminology for our documents
5.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.
5.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.
Gondwana Expires 24 February 2021 [Page 6]
Internet-Draft Effective Terminology August 2020
5.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 choice always rests with the 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.
5.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.
TODO: 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. I am not
specifying that form here and am looking for input - Bron.
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.
6. 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)
Gondwana Expires 24 February 2021 [Page 7]
Internet-Draft Effective Terminology August 2020
7. 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.
8. Changes
EDITOR: please remove this section before publication.
8.1. 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!
9. Acknowledgements
Author's Address
Bron Gondwana (editor)
Fastmail
Level 2, 114 William St
Melbourne VIC 3000
Australia
Email: brong@fastmailteam.com
URI: https://www.fastmail.com
Gondwana Expires 24 February 2021 [Page 8]