Subject: [Lime] Adam Roach's No Objection on draft-ietf-lime-yang-connectionless-oam-14: (with COMMENT)

From: Adam Roach <[email-masked]>
Date: Wed, 25 Oct 2017 12:19:17 -0700

Adam Roach has entered the following ballot position for
draft-ietf-lime-yang-connectionless-oam-14: No Objection

When responding, please keep the subject line intact and reply to all
email addresses included in the To and CC lines. (Feel free to cut this
introductory paragraph, however.)

Please refer to https://www.ietf.org/iesg/statement/discuss-criteria.html
for more information about IESG DISCUSS and COMMENT positions.

The document, along with other ballot positions, can be found here:
https://datatracker.ietf.org/doc/draft-ietf-lime-yang-connectionless-oam/

----------------------------------------------------------------------
COMMENT:
----------------------------------------------------------------------

I'd like to update my comment with some fairly mechanical suggestions for
improvement that I believe will increase readability of the document greatly.
In evaluating this document, I found a number of minor formatting issues that
made it somewhat difficult to read.

1. Please ensure that all opening parentheses have a space before them and no
space after them.

2. Please ensure that all closing parentheses have a space after them and no
space before after them.

3. Please ensure that all quoted terms include both an opening quotation mark
and a closing quotation mark.

4. Please ensure that there are no spaces between a quotation mark and the term
it is quoting.

5. Please ensure that there *is* a space before an opening quotation mark

6. Please ensure that there *is* a space after a closing quotation mark (unless
followed by another punctuation mark)

7. Please ensure that periods at the end of a sentence have no space before
them and a space after them.

8. Please break up long paragraphs into separate paragraphs or bullet lists.
The third paragraph of section 3 and the paragraph that forms section 3.3 are
prime candidates for such an improvement.

9. Please double-check the formatting of the YANG module. The indentation is
inconsistent and, in some places, can easily mislead the reader about the level
of nesting and association of elements with each other.

My original comments follow.

------------------------------------------------------------

Please expand "EXP", "VPLS", and "LAG" on first use.

Section 3.2 refers to the "lime base model". Please define or expand "lime" or
provide a citation that does so.

The id-nits tool reports that there are 6 instances of overly-long lines in the
document. Given that these exist in code elements, the authors can probably
make better decisions about how to resolve these than the RFC editor can.

Section 3.3 contains the following definition:

                list oam-neighboring-tps {
                  key "index";
                  leaf index {
                     type uint16 {
                        range "0..65536";
                     }

uint16 cannot represent 65536.

----------------------------------------

Later in the model:

 container timestamp-80bit {
 when "derived-from-or-self(../timestamp-type, 'cl-oam:ptp80')"{
         description
          "Only applies when 80bit PTP Timestamp.";
        }
  if-feature ptp-long-format;
      leaf timestamp-sec {
      type uint64 {
      range "0..281474976710656";
      }
      description
        "48bit Timestamp in seconds as per IEEE1588v2.";
       }
      leaf timestamp-nanosec {
      type uint32;
      description
        "Fractional part in nanoseconds as per IEEE1588v2
         or Fractional part in 64-bit NTP timestamp.";
      }
      description
      "Container for 64bit timestamp.";
    }

Issue 1: The 48-bit range should be 0..281474976710655, not 0..281474976710656

Issue 2: The description for this 80-bit timestamp container contains a
description of "Container for 64bit timestamp."

----------------------------------------

Similar to issue 2 above, ntp-timestamp-32bit describes itself as a 64-bit
timestamp.

---

From: Benoit Claise <[email-masked]>
Date: Wed, 25 Oct 2017 19:09:53 -0700

Dear authors and document shepherd,

If you recall my AD review (on the LIME mailing list)

    My quick summary:
    Those two LIME drafts are hard to read. I've been spending hours to
    try to understand...
    I advice the authors, shepherd, chairs to review the two drafts with
    a fresh mind and improve readability.

Multiple IESG members had similar COMMENTS regarding readability.
These are not DISCUSSES, but you should anyway improve the document to 
address this point, starting with Adam's list.

Regards, Benoit
> .

---

From: Qin Wu <[email-masked]>
Date: Thu, 26 Oct 2017 02:51:30 +0000

Thanks Adam for valuable review and sanity check.
See my reply below.
-----邮件原件-----
发件人: Lime [mailto:[email-masked]] 代表 Adam Roach
发送时间: 2017年10月26日 3:19
收件人: The IESG
抄送: Ron Bonica; [email-masked]; [email-masked]; [email-masked]; [email-masked]
主题: [Lime] Adam Roach's No Objection on draft-ietf-lime-yang-connectionless-oam-14: (with COMMENT)

When responding, please keep the subject line intact and reply to all email addresses included in the To and CC lines. (Feel free to cut this introductory paragraph, however.)

I'd like to update my comment with some fairly mechanical suggestions for improvement that I believe will increase readability of the document greatly.
In evaluating this document, I found a number of minor formatting issues that made it somewhat difficult to read.

1. Please ensure that all opening parentheses have a space before them and no space after them.
2. Please ensure that all closing parentheses have a space after them and no space before after them.

3. Please ensure that all quoted terms include both an opening quotation mark and a closing quotation mark.

4. Please ensure that there are no spaces between a quotation mark and the term it is quoting.

6. Please ensure that there *is* a space after a closing quotation mark (unless followed by another punctuation mark)

7. Please ensure that periods at the end of a sentence have no space before them and a space after them.

8. Please break up long paragraphs into separate paragraphs or bullet lists.
The third paragraph of section 3 and the paragraph that forms section 3.3 are prime candidates for such an improvement.

9. Please double-check the formatting of the YANG module. The indentation is inconsistent and, in some places, can easily mislead the reader about the level of nesting and association of elements with each other.

 [Qin]: Good catch, will fix these formatting issues. Many thanks
My original comments follow.

[Qin]: Good comment, will add them as new acronyms in abbreviation section.

Section 3.2 refers to the "lime base model". Please define or expand "lime" or provide a citation that does so.

[Qin]: Okay.

The id-nits tool reports that there are 6 instances of overly-long lines in the document. Given that these exist in code elements, the authors can probably make better decisions about how to resolve these than the RFC editor can.

[Qin]: Don't have a good tool to track this, but yes will fix this. Thanks.

[Qin]: Okay.

Later in the model:

Issue 2: The description for this 80-bit timestamp container contains a description of "Container for 64bit timestamp."

Similar to issue 2 above, ntp-timestamp-32bit describes itself as a 64-bit timestamp.

[Qin]:Fixed, thanks for updating comments.
_______________________________________________
Lime mailing list
[email-masked]
https://www.ietf.org/mailman/listinfo/lime