Subject: [AVT] Comments on draft-ietf-avt-rapid-acquisition-for-rtp-09

From: "DRAGE, Keith (Keith)" <[email-masked]>
Date: Wed, 26 May 2010 19:27:56 +0200

In no particular order, these are my general comments on the document:

1)	Too many "SHOULD"s throughout document. The impression I got was that the ratio of SHOULDs against MUSTs is higher than I would expect to see (15 SHOULD and 57 MUST). If we really mean "SHOULD" rather than "MAY" then we should be detailing at least some examples to give guidance to the implementor as to when it is permissible to break the recommendation of the "SHOULD". If we really mean If <condition which was rather complex> then MUST, then I'm sorry but you need to put the work in to detail the conditions.

So I would request the editor's to go through the document and check all the SHOULD requirements are really what is meant.

2)	Many requirements are prefixed by text, e.g. "Thus," It appears that the intention is not to have this alter the meaning of the requirement, but to indicate why the requirement exists. However the "thus" could be interpreted as a conditional on the requirement itself. Better to delete these preambles.

Example:

        Note that if FT_Ap is associated with
        two or more RTP sessions, RTP_Rx's request will be ambiguous.
        Thus, each FT_Ap MUST be associated with a single RTP session.

Does the requirement only apply when the request is ambiguous?

Example:

	Note that this TLV
      element does not carry a Value field.  Thus, the Length field MUST
      be set to zero.

(I have other problems with the above (from section 7.2) because surely the length has to indicate the length, and this requirement follows a SHOULD that allows other contents which should surely be taken account of in the length.)

3)	"Note that". Do not use in conjunction with normative language, as many readers used to other standards bodies treat all information following it as informative (i.e. ignore for the purpose of conformance). In most cases it is superfluous anyway. 

Example (from section 7.3):

      Note that BRS MUST terminate the flow in a deterministic
      timeframe, even if it does not get a RAMS-T or a BYE from RTP_Rx.

To be honest, I would just delete all such sentence preambles, whether the following text is normative or informative. In 90% of the cases the reader will not notice the difference.

4)	Ditto to the above, "For example".

Example (from section 7.3):

      For example, if FT_Ap
      that received the RAMS-R message is associated with a single
      primary multicast stream but the requested media sender SSRC does
      not match the SSRC of the RTP stream associated with this FT_Ap,
      BRS SHOULD include this TLV element in the initial RAMS-I message
      to let RTP_Rx know that the media sender SSRC has changed.

5)	Please ensure all RFC 2119 language can be assessed from a viewpoint of conformance. Make sure that the entity to which the requirements applies is clear, ideally by including it in the same sentence, and ideally somewhere near the verb. That means writing requirements in the active sense ("xxx MUST perform the following yyy", not "yyy MUST be performed", and not "the message MUST contain yyy"). Clearly think about how we test each requirement that contains RFC 2119 language, as we will need to understand that if this ever goes near draft standard.

Some examples but please go through all the requirements.

>From section 6.2.

        If
        RTP_Rx desires to rapidly acquire only a subset of the primary
        multicast streams available in the primary multicast RTP
        session, the SSRC identifiers for the desired RTP streams MUST
        also be obtained out-of-band.

        Thus, each FT_Ap MUST be associated with a single RTP session.

        If the request is accepted, this information MUST be
        conveyed in at least one RAMS-I message and its value MAY be
        updated by subsequent RAMS-I messages.

5)	Do not mix different requirements on two separate entities in the same sentence. Ideally try and keep them in separate paragraphs.

Example (from section 6.2):

           Reject Responses:  BRS MUST take into account any limitations
           that MAY have been specified by RTP_Rx in the RAMS-R message
           when making a decision regarding the request.

6)	Clearly separate the requirements on the vendor (that relate to extensions) from requirements on the implementation.

This is primarily aimed at section 7.1.2. 

   It is desirable to allow vendors to use private extensions in a TLV
   format.  For interoperability, such extensions MUST NOT collide with
   each other.

This appears to be a requirement on the vendor not to define extensions that collide, and no amount of testing of the implementation will ever determine lack of conformance to this. Then in the same section we have:

   The structure that MUST be used for the private extensions is
   depicted in Figure 6.

Which is presumably a requirement on the implementations.

It may be that we don't actually need the first MUST in this section at all, but I'll let the editor's debate that.

7)	In the IANA registration clauses, I don't believe we need any RFC 2119 language. This section is meant to be telling IANA how to handle registration requests. They do that by contract. It may be that you need the normative language elsewhere.

8)	The document uses pre 2008 boilerplate. Can we address getting permission from any of the prior contributers for the full IETF boilerplate, or has that already been determined to be impossible. Who are the contributors of text for which the status is not known?

9)	Abbreviated names. If we define an abbreviation, can we use it expanded in full on the first occurrence, and then abbreviate it on every other instance in the document. I assume RTP receiver is the same as RTP_Rx. Ditto Feedback Target (FT) is another example of inconsistent usage. Retransmission server and (RS). If you consider the abbreviation makes the understanding opaque, then don't use it at all. Given the number of abbreviations, it may be appropriate to have a separate section early in the document listing them (or reduce the number). Some abbreviations never appear expanded, and the assumption is made that they are well known to all readers; not sure this should be assumed (e.g. SSRC, TLV).

10)	Lower case version of RFC 2119 language. I prefer to avoid using these, as it is so easy in some cases for the upper case form to get substituted on editing. In many cases there are substitutes that avoid this confusion. I could make an exception to this for section 5, but please indicate clearly at the start of the section that it does not contain requirements for implementation.

I'll send the editor's directly my marked up version which has a number of editorial suggestions.

regards

Keith

---

From: "Ali C. Begen (abegen)" <[email-masked]>
Date: Wed, 26 May 2010 11:16:25 -0700

Hi Keith,

Thanks for the review. See inline.

> -----Original Message-----
> From: [email-masked] [mailto:[email-masked]] On Behalf Of DRAGE, Keith (Keith)
> Sent: Wednesday, May 26, 2010 1:28 PM
> To: [email-masked]
> Cc: [email-masked]
> Subject: [AVT] Comments on draft-ietf-avt-rapid-acquisition-for-rtp-09
> 
> 1)	Too many "SHOULD"s throughout document. The impression I got was that the ratio of SHOULDs
> against MUSTs is higher than I would expect to see (15 SHOULD and 57 MUST). If we really mean "SHOULD"

I did not count the 2119 words, are you saying 15 SHOULDs are too many? Regardless of how many SHOULDs or MUSTs exist, we tried to be careful in choosing our language and incorporated feedback from many folks so far.

We will check the edited doc you sent and make changes if necessary.

> rather than "MAY" then we should be detailing at least some examples to give guidance to the
> implementor as to when it is permissible to break the recommendation of the "SHOULD". If we really
> mean If <condition which was rather complex> then MUST, then I'm sorry but you need to put the work in
> to detail the conditions.

It is not about complexity. It is about how the implementation prefers of doing it. For example, we say "the server SHOULD do something" but an implementation may not really prefer doing it that way or at that particular time. This is a compromise we need to have multiple implementations converge on a common protocol.
 
> 2)	Many requirements are prefixed by text, e.g. "Thus," It appears that the intention is not to
> have this alter the meaning of the requirement, but to indicate why the requirement exists. However
> the "thus" could be interpreted as a conditional on the requirement itself. Better to delete these
> preambles.
> 
> Example:
> 

Hmm, I don't get that meaning. There is no "if" before or after "MUST" in the same sentence. We give a reason, and then we say for this reason, we have this rule.
 
>       element does not carry a Value field.  Thus, the Length field MUST

This could be rephrased as:

"This TLV element does not carry a Value field and the Length field MUST be set to zero."
 
> (I have other problems with the above (from section 7.2) because surely the length has to indicate the
> length, and this requirement follows a SHOULD that allows other contents which should surely be taken
> account of in the length.)
> 
> 3)	"Note that". Do not use in conjunction with normative language, as many readers used to other
> standards bodies treat all information following it as informative (i.e. ignore for the purpose of
> conformance). In most cases it is superfluous anyway.
> 
> To be honest, I would just delete all such sentence preambles, whether the following text is normative
> or informative. In 90% of the cases the reader will not notice the difference.

Will check.
 
>       to let RTP_Rx know that the media sender SSRC has changed.

It is a good practice to use "For example" in certain cases. There might be some redundant ones but not necessarily all of them are redundant. Will check this as well.
 
> 5)	Please ensure all RFC 2119 language can be assessed from a viewpoint of conformance. Make sure
> that the entity to which the requirements applies is clear, ideally by including it in the same
> sentence, and ideally somewhere near the verb. That means writing requirements in the active sense
> ("xxx MUST perform the following yyy", not "yyy MUST be performed", and not "the message MUST contain
> yyy"). Clearly think about how we test each requirement that contains RFC 2119 language, as we will
> need to understand that if this ever goes near draft standard.
> 

You will need to tell me what is wrong above. Both 2119 keywords are correct AFAICT and they are not confused with each other.
 
>            when making a decision regarding the request.

Since "MAY" part was explained before, the one here could be dropped.
 
> This appears to be a requirement on the vendor not to define extensions that collide, and no amount of
> testing of the implementation will ever determine lack of conformance to this. Then in the same
> section we have:
> 

Good catch. The first MUST should not be there. 
 
> 7)	In the IANA registration clauses, I don't believe we need any RFC 2119 language. This section is
> meant to be telling IANA how to handle registration requests. They do that by contract. It may be that
> you need the normative language elsewhere.

There are examples that use 2119 language in IANA section. That language tells the registration requirements/guidelines to someone who wants to register something with IANA in these registries.
 
> 8)	The document uses pre 2008 boilerplate. Can we address getting permission from any of the prior
> contributers for the full IETF boilerplate, or has that already been determined to be impossible. Who
> are the contributors of text for which the status is not known?

First of all, is there a problem with the pre2008 boilerplate? This is a sensitive issue for several folks and I don't wanna open a can of worms here for no good reason.

> 
> 9)	Abbreviated names. If we define an abbreviation, can we use it expanded in full on the first
> occurrence, and then abbreviate it on every other instance in the document. I assume RTP receiver is
> the same as RTP_Rx. Ditto Feedback Target (FT) is another example of inconsistent usage.
> Retransmission server and (RS). If you consider the abbreviation makes the understanding opaque, then
> don't use it at all. Given the number of abbreviations, it may be appropriate to have a separate
> section early in the document listing them (or reduce the number). Some abbreviations never appear
> expanded, and the assumption is made that they are well known to all readers; not sure this should be
> assumed (e.g. SSRC, TLV).

If SSRC needs to be expanded, we will do so. 
For TLV, right after it was first used, T, L and V were explained but I will make this clear.

And RTP_Rx, we can convert all "RTP receiver" occurrences to RTP_Rx, but in certain sections, the context is somewhat standalone and that is why we kept "RTP receiver". Find/replace is easy, though if you think we should convert all of them.

> 
> 10)	Lower case version of RFC 2119 language. I prefer to avoid using these, as it is so easy in some
> cases for the upper case form to get substituted on editing. In many cases there are substitutes that
> avoid this confusion. I could make an exception to this for section 5, but please indicate clearly at
> the start of the section that it does not contain requirements for implementation.

OK.
 
> I'll send the editor's directly my marked up version which has a number of editorial suggestions.

Thanks , we will go over it.

-acbegen
 
> 
> regards
> 
> Keith
> _______________________________________________
> Audio/Video Transport Working Group
> [email-masked]
> https://www.ietf.org/mailman/listinfo/avt

---

From: Colin Perkins <[email-masked]>
Date: Thu, 27 May 2010 15:22:46 +0100

I agree with these comments. The draft is not particularly easy to  
read, and the suggestions below would improve it significantly.

Colin

On 26 May 2010, at 18:27, DRAGE, Keith (Keith) wrote:
> 1)	Too many "SHOULD"s throughout document. The impression I got was  
> that the ratio of SHOULDs against MUSTs is higher than I would  
> expect to see (15 SHOULD and 57 MUST). If we really mean "SHOULD"  
> rather than "MAY" then we should be detailing at least some examples  
> to give guidance to the implementor as to when it is permissible to  
> break the recommendation of the "SHOULD". If we really mean If  
> <condition which was rather complex> then MUST, then I'm sorry but  
> you need to put the work in to detail the conditions.
>
> So I would request the editor's to go through the document and check  
> all the SHOULD requirements are really what is meant.
>
> 2)	Many requirements are prefixed by text, e.g. "Thus," It appears  
> that the intention is not to have this alter the meaning of the  
> requirement, but to indicate why the requirement exists. However the  
> "thus" could be interpreted as a conditional on the requirement  
> itself. Better to delete these preambles.
>
> Example:
>
> (I have other problems with the above (from section 7.2) because  
> surely the length has to indicate the length, and this requirement  
> follows a SHOULD that allows other contents which should surely be  
> taken account of in the length.)
>
> 3)	"Note that". Do not use in conjunction with normative language,  
> as many readers used to other standards bodies treat all information  
> following it as informative (i.e. ignore for the purpose of  
> To be honest, I would just delete all such sentence preambles,  
> whether the following text is normative or informative. In 90% of  
> the cases the reader will not notice the difference.
>
> 5)	Please ensure all RFC 2119 language can be assessed from a  
> viewpoint of conformance. Make sure that the entity to which the  
> requirements applies is clear, ideally by including it in the same  
> sentence, and ideally somewhere near the verb. That means writing  
> requirements in the active sense ("xxx MUST perform the following  
> yyy", not "yyy MUST be performed", and not "the message MUST contain  
> yyy"). Clearly think about how we test each requirement that  
> contains RFC 2119 language, as we will need to understand that if  
> this ever goes near draft standard.
>
> 5)	Do not mix different requirements on two separate entities in the  
> same sentence. Ideally try and keep them in separate paragraphs.
>
> 6)	Clearly separate the requirements on the vendor (that relate to  
> extensions) from requirements on the implementation.
>
> This appears to be a requirement on the vendor not to define  
> extensions that collide, and no amount of testing of the  
> implementation will ever determine lack of conformance to this. Then  
> in the same section we have:
>
> It may be that we don't actually need the first MUST in this section  
> at all, but I'll let the editor's debate that.
>
> 7)	In the IANA registration clauses, I don't believe we need any RFC  
> 2119 language. This section is meant to be telling IANA how to  
> handle registration requests. They do that by contract. It may be  
> that you need the normative language elsewhere.
>
> 8)	The document uses pre 2008 boilerplate. Can we address getting  
> permission from any of the prior contributers for the full IETF  
> boilerplate, or has that already been determined to be impossible.  
> Who are the contributors of text for which the status is not known?
>
> 9)	Abbreviated names. If we define an abbreviation, can we use it  
> expanded in full on the first occurrence, and then abbreviate it on  
> every other instance in the document. I assume RTP receiver is the  
> same as RTP_Rx. Ditto Feedback Target (FT) is another example of  
> inconsistent usage. Retransmission server and (RS). If you consider  
> the abbreviation makes the understanding opaque, then don't use it  
> at all. Given the number of abbreviations, it may be appropriate to  
> have a separate section early in the document listing them (or  
> reduce the number). Some abbreviations never appear expanded, and  
> the assumption is made that they are well known to all readers; not  
> sure this should be assumed (e.g. SSRC, TLV).
>
> 10)	Lower case version of RFC 2119 language. I prefer to avoid using  
> these, as it is so easy in some cases for the upper case form to get  
> substituted on editing. In many cases there are substitutes that  
> avoid this confusion. I could make an exception to this for section  
> 5, but please indicate clearly at the start of the section that it  
> does not contain requirements for implementation.
>

-- 
Colin Perkins
http://csperkins.org/