Subject: Re: [rtcweb] 2119 language in requirements (Re: Review of draft-ietf-rtcweb-use-cases-and-requirements-10 (Part I))

From: Bernard Aboba <[email-masked]>
Date: Fri, 1 Feb 2013 21:15:23 +0000

I cannot find an RFC that deals with normative language in requirements documents specifically. Part of the reason for that may be that requirements documents are by no means uniform.  Some are created to assist in making a selection between competing protocols.  Some are just created to inform subsequent WG protocol design efforts.  Sometimes the eventual output is evaluated against the requirements, sometimes not.  With such a level of variation, it is not clear me that “one size fits all”.  

Overall, I’d say it is up to IETF RTCWEB (and W3C WEBRTC) to decide how it wants the requirements document to be used, and this in turn will influence what the normative language will mean.  Judging by the number of issues we have had with requirements documents in the past (e.g. typically the understanding of the problem evolves considerably over time and often initially specified requirements are “overtaken by events”), we should be careful about setting expectations too high. 

From: Harald Alvestrand
Sent: ‎January‎ ‎30‎, ‎2013 ‎2‎:‎02‎ ‎AM
To: [email-masked]
Subject: [rtcweb] 2119 language in requirements (Re: Review of draft-ietf-rtcweb-use-cases-and-requirements-10 (Part I))

Bernard, with your IAB hat on - didn't we do a document describing how to do 2119 language in requirements at one time?
(Since the word "requirements" occurs so often in 2119 itself, it's hard to google for it)

Failing that, I support adapting the language of RFC 2928 (needs adapting, because we're expecting to develop a single specification suite rather than evaluating multiple submissions) and inserting it here.

On 01/29/2013 11:36 PM, Bernard Aboba wrote:

I have a very fundamental question about this document:

What are the Browser and API requirements going to be used for? 

Is the goal to document things we thought might have been nice at the time?

In many cases, the requirements are too vague to easily determine whether subsequent IETF
protocol profiles or W3C API documents actually satisfy the requirements.  But even if they were
made more specific, is there really any intent to evaluate IETF and W3C work based on these requirements?

Section 2 states that normative keywords are to be interpretted as described in RFC 2119.
Since this isn't a protocol specification, does that really make sense?

As an example, requirement F3 states:

"Transmitted streams and data MUST be rate controlled."

While the statement above might make some sense in the context of the "circuit breakers" document, or
perhaps one of the congestion control documents, I don't understand what the MUST means in the context of
this document. 

Does it mean that the specifications are required to define a rate control feature? 
Assuming such a feature is defined, does it mean that browsers are required to implement the feature? 
If implementation is required, is it required that the feature be used? 

Personally, my guess is that the meaning probably does not correspond to any of the above, because this 
is only a use case document, not a protocol or API specification.

But if that is true, why point to the RFC 2119 definition of normative terms? 

In the past, a number of requirements documents have tackled this problem by explicitly
stating that how normative language is to be interpretted, rather than blindly inserting a 
reference to RFC 2119.  For example, RFC 2989 states:

   Please note that the requirements specified in this document are to
   be used in evaluating... protocol submissions.  As such, the
   requirements language refers to capabilities of these protocols; the
   protocol documents will specify whether these features are required,
   recommended, or optional.  For example, requiring that a protocol
   support confidentiality is NOT the same thing as requiring that all
   protocol traffic be encrypted.

_______________________________________________
rtcweb mailing list
[email-masked]
https://www.ietf.org/mailman/listinfo/rtcweb

---

From: Spencer Dawkins <[email-masked]>
Date: Thu, 07 Feb 2013 14:29:27 -0600

> I cannot find an RFC that deals with normative language in requirements documents specifically. Part of the reason for that may be that requirements documents are by no means uniform.  Some are cre…

I thought the IESG had done an IESG Statement on the use of normative 
language in Informational documents in general, but I'm not seeing that, 
either. I know it was discussed, but I'm not seeing that it was produced.

I also checked at the RFC Editor site, but what I found (example: 
http://www.rfc-editor.org/rfc-editor/instructions2authors.txt) doesn't 
provide guidance about 2119 for documents that aren't standards-track.

> Overall, I’d say it is up to IETF RTCWEB (and W3C WEBRTC) to decide how it wants the requirements document to be used, and this in turn will influence what the normative language will mean.  Judgin…

I agree with Bernard here.

Spencer

---

From: "DRAGE, Keith (Keith)" <[email-masked]>
Date: Tue, 19 Feb 2013 18:26:29 +0100

Where the document is an informational document containing only the requirements, I don't think it matters whether upper case or lower case is used. The field of application of such a requirements document is the resultant solution / specification documents, rather than the implementor directly.

The issue is more difficult where requirements and solution are mixed in the same document, but that does not apply in this case. Where I have dealt with drafts that fall into this case before, we have moved the requirements to an appendix to make very clear they are informative.

Keith

> -----Original Message-----
> From: [email-masked] [mailto:[email-masked]] On Behalf
> Of Spencer Dawkins
> Sent: 07 February 2013 20:29
> To: [email-masked]
> Subject: Re: [rtcweb] 2119 language in requirements (Re: Review of draft-
> ietf-rtcweb-use-cases-and-requirements-10 (Part I))
> 
> > I cannot find an RFC that deals with normative language in requirements
> documents specifically. Part of the reason for that may be that
> requirements documents are by no means uniform.  Some are created to
> assist in making a selection between competing protocols.  Some are just
> created to inform subsequent WG protocol design efforts.  Sometimes the
> eventual output is evaluated against the requirements, sometimes not.
> With such a level of variation, it is not clear me that "one size fits
> all".
> 
> > Overall, I'd say it is up to IETF RTCWEB (and W3C WEBRTC) to decide how
> it wants the requirements document to be used, and this in turn will
> influence what the normative language will mean.  Judging by the number of
> issues we have had with requirements documents in the past (e.g. typically
> the understanding of the problem evolves considerably over time and often
> initially specified requirements are "overtaken by events"), we should be
> careful about setting expectations too high.
>

---

From: Richard Barnes <[email-masked]>
Date: Tue, 19 Feb 2013 12:29:04 -0500

Keith's summary pretty much agrees with my understanding.

On Tue, Feb 19, 2013 at 12:26 PM, DRAGE, Keith (Keith) <
[email-masked]> wrote:

> Where the document is an informational document containing only the
> requirements, I don't think it matters whether upper case or lower case is
> used. The field of application of such a requirements document is the
> resultant solution / specification documents, rather than the implementor
> directly.
>
> The issue is more difficult where requirements and solution are mixed in
> the same document, but that does not apply in this case. Where I have dealt
> with drafts that fall into this case before, we have moved the requirements
> to an appendix to make very clear they are informative.
>
> Keith
>