Re: [Lsr] Barry Leiba's No Objection on draft-ietf-isis-yang-isis-cfg-37: (with COMMENT)

["Acee Lindem (acee)" <[e-mail]>]

Hi Barry, 
Thanks for your review - I've published the -38 version incorporating all your comments and Stewart Bryant's comments in order to avoid duplicates from other reviewers. I did take a pass over the document and added some additional articles. 
Thanks,
Acee

On 9/26/19, 1:37 AM, "Barry Leiba via Datatracker" <[e-mail]> wrote:

    Barry Leiba has entered the following ballot position for
    draft-ietf-isis-yang-isis-cfg-37: 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-isis-yang-isis-cfg/
    
    
    
    ----------------------------------------------------------------------
    COMMENT:
    ----------------------------------------------------------------------
    
    Thanks for the work on this YANG module.  My comments are all editorial, and
    there’s no need for a response... please just consider these, as they will help
    make the document clearer.
    
    Throughout the document, please hyphenate the following as shown here:
    per-topology basis
    per-interface basis
    per-level configuration
    per-level value
    level-specific parameter
    interface-specific parameter
    vendor-specific
    
    When you use “like” to mean “such as”, it’s ambiguous: “like” can also
    introduce a comparison, so does “fruit, like an apple” mean any fruit (and an
    apple is an example), or are you talking specifically about fruit that is in
    some way similar to an apple?  It’s better to say “such as”, to avoid the
    ambiguity.  All instances of “like” in the document should be changed, *except*
    for “encoded as a MAC address like” on page 35 and “would like to thank” in the
    Contributors section.
    
    Other, specific comments:
    
    — Section 2.1 —
    
       The model implements features, thus some of the configuration
       statement becomes optional.
    
    This is an odd sentence that I’m having a hard time understanding.  Do you mean
    this?:
    
    NEW
       This model includes optional features, for which the corresponding
       configuration statements are optional.
    END
    
       By advertising the feature "admin-control", a device communicates to
       the client that it supports the ability to shutdown a particular IS-
       IS instance.
    
    The verb “shut down” is two words.
    
    — Section 2.2 —
    
       Some specific parameters can be defined on a per topology basis both
       at global level and at interface level
    
    Apart from adding a hyphen in “per-topology basis”, you need “the” before both
    “global” and “interface”.  There are many places throughout the document where
    articles (usually “the”, but sometimes “a” or “an”) are missing.  Someone
    familiar with the correct use of articles should take a pass through the
    document.
    
    — Section 2.3 —
    In the last two paragraphs of the section, one uses “should” advertise and the
    other uses “SHOULD” advertise.  They should either both be BCP 14 key words, or
    both not.
    
    — Section 2.6 —
    
       The goal of this empty
       container is to allow easy augmentation with additional parameters
       like timers for example.
    
    As I noted above, you should use “such as”, rather than “like”, and you don’t
    *also* need “for example”, because “such as” already has that covered.  So,
    “...additional parameters, such as timers.”
    
    — Section 2.8 —
    
       The "candidate-enable" allows to mark an interface to be used as a
       backup.
    
    You need a subject for the verb after “allows” or “requires”.  It has to allow
    <something> to mark an interface, and you can’t omit the <something>.  So what
    is it?
    
    If there really is no sensible entity to put there, you can use passive voice,
    ‘The "candidate-enable" option allows an interface to be marked for use as a
    backup.’
    
    — Section 2.9 —
    Throughout the section, “information” is a collective noun; we don’t say
    “informations”.
    
    — Section 4 —
    The first four notification descriptions start with “raised when”, and the rest
    start with “This notification is sent when”.  Please make them consistent, one
    way or the other.
    
    — Section 5 —
    
       Some IS-IS specific routes attributes are added to route objects
    
    I think this is supposed to say, “Some IS-IS-specific route attributes are
    added...” (add another hyphen and take the “s” off “routes”).