Re: Genart telechat review of draft-ietf-ippm-twamp-yang-11

[Pete Resnick <[e-mail]>]

Hi Mahesh,

Trimming a bit:

On 20 Jun 2018, at 0:36, Mahesh Jethanandani wrote:


>> 3.1 - s/The test session name that MUST be identical/The test session 
>> name,
>> which MUST be identical (Unless you mean something really weird that 
>> I don't
>> think you mean. If you don't see the difference, then trust me, you 
>> mean
>> "which", not "that”.)
>
> You mean in Section 3.3.

Yes, sorry about that. Section 3.1 has a similar problem:

s/The test session name that uniquely identifies/The test session name, 
which uniquely identifies

and I forgot to note that one.

> How about s/The test session name that MUST be identical with the/The 
> test session name MUST be identical to the/?

That's not quite right. You are giving a list of fields (as you say, 
"Primary configuration fields include:"), so you don't want something in 
that list that is a rule. The field is "the test session name", and that 
field MUST be identical to the client name.

When you say, "the test session name that MUST be identical with...", it 
sounds like there is more than one test session name, and you're talking 
about the one that MUST be identical with the client name. Similarly 
with the above, it sounds like there's one test session name which 
uniquely identifies it, and one that doesn't uniquely identify it. 
That's not what you mean.

>> 4.1 -
>>
>> OLD
>>   Specifically, mode-preference-chain lists the
>>   mode and its corresponding priority, expressed as a 16-bit unsigned
>>   integer, where zero is the highest priority and subsequent integers
>>   increase by one.
>>
>> This is a bit confusing. I think you mean:
>>
>> NEW
>>   Specifically, mode-preference-chain lists the mode and its
>>   corresponding priority, expressed as a 16-bit unsigned integer.
>>   Values for the priority start with zero, the highest priority, and
>>   subsequent priority value increases by one.
>
> I can see why this can be confusing. How about ...
>
> NEW
>    Specifically, mode-preference-chain lists the
>    mode and its corresponding priority as a 16-bit unsigned
>    integer. Values for the priority start with zero, the highest 
> priority, and
>    decreasing priority value is indicated by every increase of value 
> by one.

That's fine. It's a little verbose, but the RFC Editor can suggest any 
wordsmithing if necessary during their edit.

>> OLD
>>   In turn, each ctrl-connection holds a list of test-session-request.
>>   test-session-request holds information associated with the Control-
>>   Client for this test session.
>>
>> A bit awkward. I suggest:
>>
>> NEW
>>   In turn, each ctrl-connection holds a test-session-request list. 
>> Each
>>   test-session-request holds information associated with the
>>   Control-Client for this test session.
>
> Ok.

Thanks.

>> OLD
>>   The Control-Client is also responsible for scheduling TWAMP-Test
>>   sessions so test-session-request holds information related to these
>>   actions (e.g. pm-index, repeat-interval).
>>
>> The word "so" in there is weird. Do you mean "therefore", or "such 
>> that", or
>> something else? I just had a bit of trouble understanding what you 
>> meant.
>
> We meant “therefore”. Will make the change.

Ah, good. The other solution is to put a comma before "so".

>> 4.2 - In the penultimate paragraph, change "key-id" to either "The 
>> key-id" or
>> "The KeyID”.
>
> Will change it to “The key-id”.

Sounds good.

>> Please note: I did not thoroughly review the YANG in section 5.2 or 
>> the
>> examples in Section 6 or Appendix A. I gave them a quick run through, 
>> but did
>> not check for complete consistency with the rest of the text. The 
>> below two
>> items are simply things I happened to spot because I was looking at 
>> particular
>> pieces of the module.
>>
>> 5.2 -
>>
>>           leaf priority {
>>             type uint16;
>>             description
>>               "Indicates the Control-Client Mode preference priority
>>                expressed as a 16-bit unsigned integer, where zero is
>>                the highest priority and subsequent values
>>                monotonically increasing.";
>>           }
>>
>> I am almost positive that you don't mean "monotonically increasing". 
>> I'm
>> guessing you mean "increase by one”.
>
> Will update this description to match the comment you made above or 
> whatever we agree to.

Thanks.

>>              Depending on the Modes available in the TWAMP Server
>>              Greeting message (see Fig. 2 of RFC 7717), the
>>              this Control-Client MUST choose the highest priority
>>              Mode from the configured mode-preference-chain list.";
>>
>> Typo: "the this Control-Client”
>
> Will fix it to say “the Control-Client”.

Perfect.

> Thanks.

Thanks for your speedy reply.

pr