Subject: [newtrk] Key words to Indicate Requirement Levels

From: "Lars-Erik Jonsson (LU/EAB)" <[email-masked]>
Date: Wed, 28 Apr 2004 14:02:30 +0200

--- Initial note ---
Following up on the plenary discussion in Seoul, I thought this
list could be an appropriate forum for the 2119 discussions.
Please let me know if you think it is a strongly inappropriate
subject for this list, and let me know where it would make more
sense to discuss these issues.
--------------------

* The 2119 issue

The number of informational "requirements RFC's" published has
been increasing, and it is now a commonly used practice within
the IETF to write such documents, for cases when it is deemed
important to document an agreed foundation for a protocol
before the actual development process is started (or in
parallel). 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.

* What is the practice today?

There is currently no best practice for requirement levels in
non-specification documents, e.g. requirements documents. When
looking through the RFC archive, I have identified at least
the following 5 ways of doing this:

1) Upper case keywords are used without definition or reference
2) Upper case keywords are used with reference to RFC 2119
3) Upper case keywords are used with reference to RFC 2119,
   and an additional elaboration of their meaning is provided
   within the document itself
4) Upper case keywords are used based on definitions within
   the document itself, thus without any reference to 2119
5) No upper case keywords are used

In my view, 1 is something we should not let through our
document reviews, as that is just confusing. 4 is fine, as
well as 5, although 5 should require more elaborate text.
3 is probably also ok, but it might be better to make such
an elaboration more generally referable to simplify and
provide "general tools". The problem is 2 above, as it is
not always clear what these words mean in these contexts,
and we should take some actions to avoid that usage.

* Why should something be done?

Since the publication of requirement documents is common,
we should have a BCP for how to specify requirement levels
in such documents. The fact that all 5 (and maybe even more)
variants above are used indicates something should be done
to simplify for document writers, as well as for those
reviewing/reading the 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: Brian E Carpenter <[email-masked]>
Date: Wed, 28 Apr 2004 15:52:51 +0200

There's a deeper issue here, which is whether "requirements"
documents are a good idea in the first place.

They are tough things to write in a standards-making context.
There is a strong tendency for them to end up containing either
mutually incompatible requirements, or requirements that are
too expensive to implement in the real world. In fact, by analogy
with software development best practice, the requirements document
for a standard probably needs to be developed iteratively rather
than in advance (i.e. requirements that turn out to be incompatible
or too expensive are removed during the iterations, and ones that
turn out to be wrong are corrected).

For that reason, I think that the best approach is 5) below,
i.e. no upper case normative words. In the case of RFC 3582, we
took a specific decision to downgrade the "requirements" draft
and publish it as a "goals" document. I think this would be wise
in many cases.

IMHO we should not increase the formality of our requirements
documents, but rather the opposite.

    Brian

.

---

From: Larry Masinter <[email-masked]>
Date: Wed, 28 Apr 2004 07:54:41 -0700

>    ....  What I would appreciate then

In RFC 2542 ("Terminology and Goals for Internet Fax"),
I used ("Internet Fax" elided):

   Within this document, different levels of desirability for a protocol
   ... are indicated by different priorities, indicated in
   {braces}:

      {1} there is general agreement that this is a critical
          characteristic of any definition ...
      {2} most believe that this is an important characteristic ...
      {3} there is general belief that this is a useful feature...
          but that other factors might override;
          a definition that does not provide this element is
          acceptable.

associated with lower case keywords ("must" {1}, "may" {3},
"recommended" {2}) and occasionally other words ("desirable" {3},
"essential" {1}).

Larry

.

---

From: Alex Rousskov <[email-masked]>
Date: Wed, 28 Apr 2004 09:13:17 -0600 (MDT)

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
...
.