Subject: Fwd: I-D Action: draft-hansen-nonkeywords-non2119-04.txt

From: Dave Crocker <[email-masked]>
Date: Wed, 2 Mar 2016 23:01:51 -0800

Folks,

G'day.  We'd like to see whether there is interest in getting the 
enclosed published.

It's meant as a helpful suggestion for avoiding possible confusion in 
the use of vocabulary the IETF treats as normative.

The latest version works a bit harder to avoid appearing, itself, to be 
giving normative direction...

d/

-------- Forwarded Message --------
Subject: I-D Action: draft-hansen-nonkeywords-non2119-04.txt
Date: Fri, 26 Feb 2016 13:06:36 -0800
To: [email-masked]

A New Internet-Draft is available from the on-line Internet-Drafts 
directories.

         Title           : Non-Normative Synonyms in RFCs
         Authors         : Tony Hansen
                           D. Crocker
	Filename        : draft-hansen-nonkeywords-non2119-04.txt
	Pages           : 4
	Date            : 2016-02-26

Abstract:
    Specifications in RFCs contain normative keywords, as defined in RFC
    2119, to signify requirements, permission or prohibitions.  These
    include MUST, SHOULD and MAY, which are commonly recorded in all
    CAPITALS (but need not be).  The RFC 2119 words are sometimes also
    used with non-normative meaning; this non-normative usage can be
    confusing and it is better to restrict the RFC 2119 words to be used
    solely as normative directives.

    Happily, natural languages permit variation in phrasing, so that
    meaning can be retained without use of this otherwise-normative
    vocabulary.  For such situations, this document provides some
    alternatives to the normative vocabulary of RFC 2119.

The IETF datatracker status page for this draft is:
https://datatracker.ietf.org/doc/draft-hansen-nonkeywords-non2119/

There's also a htmlized version available at:
https://tools.ietf.org/html/draft-hansen-nonkeywords-non2119-04

A diff from the previous version is available at:
https://www.ietf.org/rfcdiff?url2=draft-hansen-nonkeywords-non2119-04

Please note that it may take a couple of minutes from the time of submission
until the htmlized version and diff are available at tools.ietf.org.

-- 

   Dave Crocker
   Brandenburg InternetWorking
   bbiw.net

---

From: Julian Reschke <[email-masked]>
Date: Thu, 3 Mar 2016 13:30:37 +0100

> giving normative direction...

Absolutely, go ahead!

---

From: Dave Cridland <[email-masked]>
Date: Thu, 3 Mar 2016 16:58:31 +0000

On 3 March 2016 at 07:01, Dave Crocker <[email-masked]> wrote:

> Folks,
>
> G'day.  We'd like to see whether there is interest in getting the enclosed
> published.
>
> It's meant as a helpful suggestion for avoiding possible confusion in the
> use of vocabulary the IETF treats as normative.
>

It's not entirely clear to me that if a specification says "support for
FOOBAR is necessary in order to support BLURDYBLOOP", that this is anything
different from "implementations MUST support FOOBAR in order to support
BLURDYBLOOP". The latter is easier to spot, of course, and might well be
preferable for that reason alone, but I would expect an implementer to
treat the two with equal weight.

RFC 2119 is, I have always assumed, for clarification of intent when making
normative statements, rather than the only way of making something
normative. This draft appears to imply, for example in the final sentence
of §4, that the RFC 2119 keywords have a particular standing in terms of
normativity. Some of the suggested alternatives are effectively stating
normative requirements; at the very least the uses when one does not intend
normative meaning are not the first things that spring to mind.

That said, providing suggested alternate phrasing when one explicitly does
not wish to evoke the meaning given in RFC 2119 is a useful thing; but
perhaps some examples of non-normative use of the English words (and
suitable rephrasings) might help reduce any confusion. "May be aware",
"must consider", "should prove useful", etc.

Also, I was going to suggest you might not mean "verbiage"; but then I
discovered the US meaning. The rest of the English-speaking world
exclusively uses the meaning of "excessively lengthy or technical speech or
writing". "Wording" or "phrasing" might work just as well, without the
alternate meaning.

Dave.

---

From: Theodore V Faber <[email-masked]>
Date: Thu, 3 Mar 2016 17:44:00 +0000

> G'day.  We'd like to see whether there is interest in getting the 

Quite excellent and useful.  A useful set of bits to be able to which
to redirect authors, to be sure.

I'm amused that it seems to already have reached version -04 and in
true bikeshed manner I'm going to suggest one more sentence.

If you skip abstracts, as I often do, the first section seems to not
frame the problem you're solving.  I'd suggest:

- ---
The IETF community tends to interpret language commonly used in
describing standards according to the rigid definitions of that
context.  Authors often find that this leads to misunderstandings and
misdirected discussions that can slow the exchange of ideas underlying
the document.  This document is a reminder of the language in question
and suggests some alternatives.
- ---

If you think that solves a problem that only I have, or that the
current more brief version is more effective, I'll neither fight the
authors on it nor be offended.

> The latest version works a bit harder to avoid appearing, itself,
> to be giving normative direction...

That was a second point that I enjoyed.

Write an RFC that prints itself.  It MUST be correctly formatted and
semantically clear.

- -- 
Ted Faber <[email-masked]>
Engineering Specialist
Computer Systems Research Department
310-336-7373

---

From: Brian E Carpenter <[email-masked]>
Date: Fri, 4 Mar 2016 11:29:03 +1300

On 04/03/2016 06:44, Theodore V Faber wrote:
> -----BEGIN PGP SIGNED MESSAGE-----
> Hash: SHA512
> 

I'm not so sure about that. When I first saw the draft several years ago,
that was my own reaction, but please consider carefully what Dave Cridland wrote:

> BLURDYBLOOP". 

When reviewing documents for Gen-ART I quite often find myself asking the
authors something like this (extracted from a recent thread on the Gen-ART list):

>>>
>>> Firstly, shouldn't that "should" be a SHOULD?
>>
>> Yes, that should be a SHOULD. Good catch

Now if that "should" had been disguised as "ought to" I would probably not
have noticed, but it ought to have been changed to "SHOULD" anyway.

So we do need precision, but IMHO adding synonyms will reduce precision,
not improve it. There are days when I think that RFC 2119 is a complete
mistake, but it does have the advantage of reducing ambiguity. Synonyms
that are superficially different but fundamentally mean the same thing
(especially for the more subtle keywords like SHOULD and MAY) increase
my confusion about what a specification really means and therefore
about what I must write in my software.

    Brian

---

From: Matthew Kerwin <[email-masked]>
Date: Fri, 4 Mar 2016 10:07:16 +1000

> have noticed, but it ought to have been changed to "SHOULD" anyway.
​This brings to mind RFC 6919.​

I'm happy to encourage disambiguation by avoiding "should" when we *don't*
mean "SHOULD," but we'd have to be quite sure that that is the case. It's
not enough to just say: 'never write "should;"' and we wouldn't want to
give anyone the impression that that's what we're saying.

Cheers
-- 
  Matthew Kerwin
  http://matthew.kerwin.net.au/