<?xml version="1.0" encoding="utf-8"?>
<!-- name="GENERATOR" content="github.com/mmarkdown/mmark Mmark Markdown Processor - mmark.miek.nl" -->
<rfc version="3" ipr="trust200902" docName="draft-gondwana-effective-terminology-01" submissionType="IETF" category="std" xml:lang="en" xmlns:xi="http://www.w3.org/2001/XInclude" consensus="true">

<front>
<title abbrev="Effective Terminology">Effective Terminology in IETF drafts</title><seriesInfo value="draft-gondwana-effective-terminology-01" stream="IETF" status="standard" name="Internet-Draft"></seriesInfo>
<author role="editor" initials="B." surname="Gondwana" fullname="Bron Gondwana"><organization>Fastmail</organization><address><postal><street>Level 2, 114 William St</street>
<city>Melbourne</city>
<code>VIC 3000</code>
<country>Australia</country>
</postal><email>brong@fastmailteam.com</email>
<uri>https://www.fastmail.com</uri>
</address></author>
<date year="2020" month="August" day="25"></date>
<area>General</area>
<workgroup>GENDISPATCH</workgroup>

<abstract>
<t>The IETF and the RFC series are trusted names, for producing high
quality technical documents that make the Internet work better.</t>
<t>While the success of our documents is variable, many of them are
widely used over a long time period.</t>
<t>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.</t>
<t>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.</t>
<t>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.</t>
</abstract>

</front>

<middle>

<section anchor="introduction"><name>Introduction</name>
<t>The IETF, and even more so the three magic letters &quot;RFC&quot;, 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.</t>
<t>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.</t>
<t>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]).</t>
<t>In the same way that &quot;Security Considerations&quot; 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.</t>
</section>

<section anchor="adapting-to-a-changing-world"><name>Adapting to a changing world</name>

<section anchor="words-have-multiple-meanings-and-change-meanings-over-time"><name>Words have multiple meanings and change meanings over time</name>
<t>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 &quot;Trump&quot;.  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.</t>
<t>Likewise, words have different meanings in different cultures, different languages,
or to different groups of humans.</t>
<t>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.</t>
</section>

<section anchor="words-can-encourage-or-discourage-participation"><name>Words can encourage or discourage participation</name>
<t>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.</t>
<t>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.</t>
<t>We remain relevant by being persuasive and welcoming to the largest
possible audience. &quot;Virtue Signalling&quot; has a dirty name, but &quot;welcome
signalling&quot; 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.</t>
<t>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.</t>
</section>

<section anchor="analogies-change-meaning-over-time"><name>Analogies change meaning over time</name>
<t>In the year 2020, the icon for &quot;save&quot; is still an image of a floppy
disk, though there are more software users every year who have never
actually used a floppy disk.</t>
<t>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.</t>
</section>

<section anchor="the-best-time-to-plant-a-tree-is-20-years-ago"><name>The best time to plant a tree is 20 years ago</name>
<t>The full proverb is &quot;the best time to plant a tree is 20 years ago,
the second best time is now&quot;.  While it is costly to change terminology,
or to replace an existing protocol, it will only be more costly in
the future!</t>
<t>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.</t>
<t>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.</t>
</section>
</section>

<section anchor="change-is-not-always-necessary"><name>Change is not always necessary</name>

<section anchor="what-we-re-doing-is-generally-working"><name>What we're doing is generally working</name>
<t>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.</t>
</section>

<section anchor="we-will-naturally-follow-emerging-consensus-in-the-wider-world"><name>We will naturally follow emerging consensus in the wider world</name>
<t>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.</t>
<t>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.</t>
</section>
</section>

<section anchor="how-to-choose-terminology-for-our-documents"><name>How to choose terminology for our documents</name>

<section anchor="engineering-considerations-take-priority"><name>Engineering considerations take priority</name>
<t>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.</t>
<t>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.</t>
<t>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.</t>
</section>

<section anchor="avoidance-of-pixie-dust"><name>Avoidance of &quot;pixie dust&quot;</name>
<t>Technical terms are often chosen based on analogies from
civilian life.</t>
<t>No analogy is 100% perfect.  There are always tradeoffs with
novelty, searchability, accessibility and confusion potential.</t>
<t>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.</t>
</section>

<section anchor="decentralised-control"><name>Decentralised control</name>
<t>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.</t>
<t>The work is done by those who show up.</t>
<t>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.</t>
<t>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.</t>
<t>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.</t>
</section>

<section anchor="centralised-knowledge"><name>Centralised knowledge</name>
<t>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.</t>
<t>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.</t>
<t>This document should reference other similar documents produced
by non-IETF groups, in order to align our language with the rest
of the world.</t>
<t>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.</t>
</section>
</section>

<section anchor="iana-considerations"><name>IANA Considerations</name>
<t>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)</t>
</section>

<section anchor="security-considerations"><name>Security Considerations</name>
<t>Bad faith actors can already interrupt the consensus process by raising
spurious and unsubstantiated complaints that look reasonable at first glance.</t>
<t>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.</t>
<t>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.</t>
</section>

<section anchor="changes"><name>Changes</name>
<t>EDITOR: please remove this section before publication.</t>
<t>The source of this document exists on github at: <eref target="https://github.com/brong/draft-gondwana-effective-terminology">https://github.com/brong/draft-gondwana-effective-terminology</eref></t>
<t><strong>draft-gondwana-effective-terminology-00</strong>
- my initial suggestions, probably needs lots of review and I imagine I've missed a lot.  Please give kind feedback!</t>
<t><strong>draft-gondwana-effective-terminology-01</strong>
- based on initial private feedback, trimmed the &quot;Background&quot; section entirely and simplified some wording.</t>
</section>

<section anchor="acknowledgements"><name>Acknowledgements</name>

<ul>
<li>I'll fill this section out once this is public and based on public feedback.</li>
</ul>
</section>

</middle>

<back>

</back>

</rfc>
