[netmod] rfc6087bis shepherd writeup issues

[Kent Watsen <[e-mail]>]

Hi Andy,


1) before I forget, could you please confirm one more time (the last time being in 2016, sheesh!) that you are unaware of any IPR that needs to be filed for this draft, according to BCPs 78 and 79?



2) Idnits found three warnings, only the first might require thought for how best to fix it:

  == Unused Reference: 'RFC5378' is defined on line 2502, but no explicit
     reference was found in the text

  == Outdated reference: A later version (-10) exists of
     draft-ietf-netmod-revised-datastores-07

  == Outdated reference: A later version (-04) exists of
     draft-ietf-netmod-yang-tree-diagrams-02



3) in the Introduction, would this be better?
 OLD
   The standardization of network configuration interfaces for use with
   ***the Network Configuration Protocol [RFC6241] and RESTCONF [RFC8040]***
   requires a modular set of data models, which can be reused and
   extended over time.
 NEW
   The standardization of network configuration interfaces for use with
   network configuration management protocols, such as NETCONF [RFC6241]
   and RESTCONF [RFC8040], requires a modular set of data models, which
   can be reused and extended over time.


4) In the next paragraph, should "server" be qualified?
   A *NETCONF or RESTCONF* server that supports
   a particular YANG module will support client NETCONF and/or RESTCONF
   operation requests, as indicated by the specific content defined in
   the YANG module.


5) The next paragraph is no longer accurate and, given its value is unless, maybe it should be removed altogether?
 OLD
   This document is similar to the Structure of Management Information
   version 2 (SMIv2) usage guidelines specification [RFC4181] in intent
   and structure.  However, since that document was written a decade
   after SMIv2 modules had been in use, it was published as a 'Best
   Current Practice' (BCP).  This document is not a BCP, but rather an
   informational reference, intended to promote consistency in documents
   containing YANG modules.


6) In the next paragraph, something seems off with the "may require" language.  Should it be just "requires" or perhaps "entails"?   Also, is it really to "maximize interoperability of NETCONF and RESTCONF implementations", or more just to make YANG modules more useful?
 OLD
   Many YANG constructs are defined as optional to use, such as the
   description statement.  However, in order to ***maximize
   interoperability of NETCONF and RESTCONF implementations utilizing
   YANG data models***, it is desirable to define a set of usage guidelines
   that ***may require*** a higher level of compliance than the minimum level
   defined in the YANG specification.


7) In the Terminology Section, please add a normative reference to RFC 8174, Section 2.  The expected result follows:
      The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL
      NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED",
      "MAY", and "OPTIONAL" in this document are to be interpreted as
      described in BCP 14 [RFC2119] [RFC8174] when, and only when, they
      appear in all capitals, as shown here.


8) Should the reference to RFC 6991 be informative instead?


9) The reference to the tree-diagrams draft being informative caught my eye. Looking into it revealed more: 
9a) I think that Section 2.5.1 should be deleted, as the draft itself does not define any tree diagrams outside of sections 3.4, which already has a reference to that draft (as it should).  
9b) should the guidelines make the Section 3.3 recommendation anymore?  - I thought that one of the main benefits of having the tree-diagrams draft was so that other drafts could easily inline-reference it, so as to avoid needing to say anything in their Terminology sections.  
9c) I think Section 3.4 should 1) say that drafts should prefix each tree-diagram with a *normative* reference to the tree-diagrams draft and 2) update the example illustrating how it might be done.
9d) Finally, back to the tree-diagrams draft being informative, yes, I guess it is informative after all.  c'est la vie  ;)


10) Should Section 8 (Changes to RFC 6087) be moved to the Introduction?  Note that the shepherd checklist says "If publication of this document changes the status of any existing RFCs, are those RFCs listed on the title page header, and are the changes listed in the abstract and discussed (explained, not just mentioned) in the introduction?"


11) I think that Section 6 (Security Considerations) should be largely moved into Section 3.7.  For this document, Section 6 should probably just say something like "This document only defines guidelines for YANG module designers and therefore does not itself have any Security considerations that need to be listed here."  What do you think?


Thanks,
Kent  // shepherd