[Docs] [txt|pdf|xml|html] [Tracker] [Email] [Diff1] [Diff2] [Nits]

Versions: 01

GENDISPATCH                                             B. Gondwana, Ed.
Internet-Draft                                                  Fastmail
Intended status: Standards Track                          25 August 2020
Expires: 26 February 2021

                  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 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 26 February 2021.

Gondwana                Expires 26 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.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   2
   2.  Adapting to a changing world  . . . . . . . . . . . . . . . .   3
     2.1.  Words have multiple meanings and change meanings over
           time  . . . . . . . . . . . . . . . . . . . . . . . . . .   3
     2.2.  Words can encourage or discourage participation . . . . .   3
     2.3.  Analogies change meaning over time  . . . . . . . . . . .   4
     2.4.  The best time to plant a tree is 20 years ago . . . . . .   4
   3.  Change is not always necessary  . . . . . . . . . . . . . . .   4
     3.1.  What we're doing is generally working . . . . . . . . . .   5
     3.2.  We will naturally follow emerging consensus in the wider
           world . . . . . . . . . . . . . . . . . . . . . . . . . .   5
   4.  How to choose terminology for our documents . . . . . . . . .   5
     4.1.  Engineering considerations take priority  . . . . . . . .   5
     4.2.  Avoidance of "pixie dust" . . . . . . . . . . . . . . . .   5
     4.3.  Decentralised control . . . . . . . . . . . . . . . . . .   6
     4.4.  Centralised knowledge . . . . . . . . . . . . . . . . . .   6
   5.  IANA Considerations . . . . . . . . . . . . . . . . . . . . .   6
   6.  Security Considerations . . . . . . . . . . . . . . . . . . .   7
   7.  Changes . . . . . . . . . . . . . . . . . . . . . . . . . . .   7
   8.  Acknowledgements  . . . . . . . . . . . . . . . . . . . . . .   7
   Author's Address  . . . . . . . . . . . . . . . . . . . . . . . .   7

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.

Gondwana                Expires 26 February 2021                [Page 2]

Internet-Draft            Effective Terminology              August 2020

   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-

   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

   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

Gondwana                Expires 26 February 2021                [Page 3]

Internet-Draft            Effective Terminology              August 2020

   work elsewhere.  If we use words that turn people away who are
   reading standards, they will bypass us and look for standards

   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

   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

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

Gondwana                Expires 26 February 2021                [Page 4]

Internet-Draft            Effective Terminology              August 2020

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

   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

4.2.  Avoidance of "pixie dust"

   Technical terms are often chosen based on analogies from civilian

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

Gondwana                Expires 26 February 2021                [Page 5]

Internet-Draft            Effective Terminology              August 2020

   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

   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)

Gondwana                Expires 26 February 2021                [Page 6]

Internet-Draft            Effective Terminology              August 2020

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

   *  I'll fill this section out once this is public and based on public

Author's Address

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

   Email: brong@fastmailteam.com
   URI:   https://www.fastmail.com

Gondwana                Expires 26 February 2021                [Page 7]

Html markup produced by rfcmarkup 1.129d, available from https://tools.ietf.org/tools/rfcmarkup/