Subject: RE: [newtrk] Key words to Indicate Requirement Levels

From: "Lars-Erik Jonsson (LU/EAB)" <[email-masked]>
Date: Thu, 29 Apr 2004 13:22:30 +0200

Brian, Alex and others,

I actually fully agree with both of you, writing requirements
documents is a tricky and questionable practice. Nevertheless,
we should have a better way to deal with them, and have better
guidelines for how to handle these kind of documents. One way
could of course be not to allow RFC publication of them, that
would make them more informal.

Personally, I have written a few requirements documents, as
that was what the WG wanted. In those cases, I've tried to
make them lightweight and more like guidelines, not using any
upper case words at all (variant 5 in my previous summary).
When the issue about upper case words was discussed in Seoul,
I got the opinion that people wanted to have defined keywords
also for these kind of documents, that is why I thought we
would have to do something in that direction. If we can get
an agreement to go in the "opposite" direction, I'd be happy.

So, how do we prohibit at least alternatives 1) and 2)? I
think we need to do something, since the current practice is
not at all clear and consistent. Making clear that 2119 can
only be referred to by technical specifications, where the
words are basically used to ensure interoperability, is one
approach I think would be ok (this is how I interpreted the
comment from Pekka Savola in Seoul).

Whether this would require an update of 2119 is not clear to
me at this stage, but updating 2119 could also be motivated
by other issues, as Alex says. When making my original post,
my idea was that we would have to update 2119 in any case
because of the way the keywords are used today, and I had
expected there could be more issues to address at the same
time. Alex, could you elaborate your thoughts, what "wider
range of documents" do you mean, and in what way do you
think the keyword definitions are not good enough for the
tech. spec. purpose?

Cheers,
/L-E

> -----Original Message-----
> From: Alex Rousskov [mailto:[email-masked]]
> Sent: den 28 april 2004 17:13
> To: Lars-Erik Jonsson (LU/EAB)
> Cc: New Track
> Subject: Re: [newtrk] Key words to Indicate Requirement Levels
> 
> 
> 
> I agree with Brian that excessive formalization of "protocol
> requirements" documents is the wrong direction. Humans are poor
> predictors, and rigid protocol requirements for yet unknown protocols
> are guaranteed to be broken when an actual protocol is specified.
> 
> Nevertheless, RFC 2119 can and should be significantly improved to
> 	- be directly applicable to a wider range of documents
> 	- better, more formally, define the keywords
> 	- define compliance/conformance model(s) based
> 	  on keywords
> 
> I am not sure you are suggesting these sort of RFC 2119 improvements
> (your post seems to be specific to protocol requirements documents).
> If you are, I would like to collaborate.
> 
> Thanks,
> 
> Alex.
> 
> P.S. FWIW, W3C QA working group has been talking about doing something
> like that for W3C, but I have not had a chance to write up a specific
> proposal.
> 
> 
> On Wed, 28 Apr 2004, Lars-Erik Jonsson (LU/EAB) wrote:
> 
> > When writing such documents, it might seem obvious
> > to refer to and use the keywords defined "for use in RFCs to
> > indicate requirement levels" in RFC 2119. However, as RFC 2119
> > was actually (this is at least how I interpret it, Scott
> > should correct me if I am wrong) written to be used for
> > technical specifications, the keyword definitions are not
> > unambiguously applicable to all requirement documents.
> ...
> > So, I was thinking of making a 2119bis proposal, if people
> > agree it would make sense. What I would appreciate then
> > would be input on how you envision keywords should be
> > defined for requirements documents, so that they would
> > be unambiguously useful in general.
> >
> > Rgds,
> > /L-E
> 
.
newtrk resources:_____________________________________________________
web user interface: http://darkwing.uoregon.edu/~llynch/newtrk.html
mhonarc archive: http://darkwing.uoregon.edu/~llynch/newtrk/index.html

---

From: "Spencer Dawkins" <[email-masked]>
Date: Thu, 29 Apr 2004 07:00:36 -0500

Ignoring all the details for a minute - I'm not just talking about
requirements documents, but something a little more global...

v6ops has produced some "analysis" documents, over a period of a
couple of years, IIRC, and is now trying to figure out whether they
are going to be BCPs or Informational.

I remember at least some of the PILC documents being written, and then
being slotted as BCP or Informational, so this question does come up
from time to time.

I'm thinking that if we produce documents (of whatever nature) and
then decide whether they are BCP, which is considered "one-level
standards-track" most of the time, or Informational, we can't be
surprised when "Informational" documents look a lot like they were
standards-track (including 2119 keywords).

Do we give enough guidance about what kinds of documents get published
on what tracks?

Spencer

.

---

From: Alex Rousskov <[email-masked]>
Date: Thu, 29 Apr 2004 11:11:17 -0600 (MDT)

On Thu, 29 Apr 2004, Lars-Erik Jonsson (LU/EAB) wrote:

> Alex, could you elaborate your thoughts, what "wider range of
> documents" do you mean,

- Documents that do not talk about specifications for software agents.
  For example, a document like RFC 2119 itself that essentially
  specifies "behavior" of other specifications. While RFC 2119
  definitions do not say "agent" explicitly, the words
  "IETF", "specification", "vendor" and a couple of examples let many
  people believe that the keywords are only useful for agents. Such
  people reinvent the wheel with their own set of keywords or
  numbers... Ideally, the scope of the keywords should be explicit
  and not limited to agents.

- Non-IETF documents. The RFC says "interpreted in IETF documents".
  It should say something like "interpreted in documents claiming
  compliance with this specification". This is less important.

> and in what way do you think the keyword definitions are not good
> enough for the tech. spec. purpose?

They are probably "good enough" in some sense, but I do not want to
use that vague metric when it comes to core IETF documents. I would
rewrite the definitions so that they are tied to compliance, which
should be defined. What happens now is that we put MUST/SHOULD/MAYs
and then either say nothing more (most of the time) or invent a
compliance model that essentially redefines MUST/SHOULD/MAYs meaning.

Take HTTP, for example. RFC 2616 defines two levels of compliance.
Full compliance means all MUSTs and SHOULDs are "satisfied".
Conditional compliance means all MUSTs are "satisfied". Thus, one can
ignore all SHOULDs and still be compliant. How does one satisfy a
SHOULD? Unknown. Note that SHOULD is defined as "there may exist valid
reasons", implying that there may not exist any reason and leaving
"valid" undefined.

I would argue for formal keyword definitions tied to conformance,
something along these lines:

	MUST -   to claim conformance, the conformance subject
                 has to act as prescribed by the requirement

        SHOULD - to claim conformance, the conformance subject
                 MUST act as prescribed by the requirement or
	         MUST provide a reason not to act as prescribed
		 by the requirement

	MAY -    to claim conformance, the conformance subject
	         MUST act as prescribed by the requirement or
		 MUST NOT act as prescribed by the requirement

Note that both SHOULD and MAY are defined in terms of MUST. The above
definitions must be polished, of course, but I hope you get the idea.

The document will also contain a section explaining how to claim
conformance with it (MUST site a formal "The key words MUST ..."
paragraph and SHOULD use capitalized keywords). IESG and RFC Editor
can then demand that whenever capitalized keywords are used, the
conformance is claimed, and check for conformance when it is claimed.

Alex.
.

---

From: Harald Tveit Alvestrand <[email-masked]>
Date: Thu, 29 Apr 2004 11:05:54 -0700

just to put another spice to the 2119 porridge:

the IESG has had a recurring discussion about whether or not 2119 language 
is appropriate for protocols published as Informational; since the IETF 
makes no requirements on these things, it could be argued that they 
shouldn't look as if the IETF does.

I've always argued strenously that the protocol writer needs all the tools 
he can get to make it clear what the *protocol* requires, and the "status" 
of the document is where the *IETF* states an opinion on the "force" of the 
document in an IETF context - so protocol writers who want to use 2119 
MUSTs should be free to do so, no matter what the classification of the 
document is.

But again, this could be an argument for making 2119 a little bit clearer.

                   Harald

.

---

From: Brian E Carpenter <[email-masked]>
Date: Thu, 29 Apr 2004 20:53:16 +0200

The IETF has always got into endless loops when attempting
to define compliance. In general, "good enough" is good
enough. So I don't think we should go one millimetre in
this direction. 2119 is good enough.

    Brian

.