Guidelines for Authors and Reviewers of YANG Data Model Documents
draft-ietf-netmod-yang-usage-11

Thanks for this document. I think it will be useful.

---

Support Enrico's point in Russ's Discuss.
It is not appropriate to keep the boilerplate outside the IETF domain.

http://trac.tools.ietf.org/wg/netconf/trac/wiki may be an appropriate
location.

---

I wonder if there is scope for some common framework text like that
held at http://www.ops.ietf.org/mib-boilerplate.html

---

I am a bit worried that this document covers advice that is more general than just the Yang-related work in an I-D. This risks setting up contradictory advice in a number of places. (For example, discussing how the References should be split is generic advice for authors of I-Ds that could be changed at any time.)

I am generally glad that this document is written. Some comments/questions below:

3.6.  Reference Sections

   For every normative reference statement which appears in a module
   contained in the specification, which identifies a separate document,
   a corresponding normative reference to that document SHOULD appear in
   the Normative References section.

Why only a SHOULD (and not a MUST)?

4.1.  Module Naming Conventions

   Modules contained in standards track documents SHOULD be named
   according to the guidelines in the IANA considerations section of
   [I-D.ietf-netmod-yang].

Why only a SHOULD?

   A distinctive word or acronym (e.g., protocol name or working group
   acronym) SHOULD be used in the module name.  If new definitions are
   being defined to extend one or more existing modules, then the same
   word or acronym should be reused, instead of creating a new one.

s/should/SHOULD ?

4.7.  Module Header, Meta, and Revision Statements

   It is acceptable to reuse the same revision statement within
   unpublished versions (i.e., Internet-Drafts), but the revision date
   MUST be updated to a higher value each time the Internet-Draft is re-
   published.

I tend to think that this MUST will be ignored in practice. I think making authors update a revision date with every uncompatible change would be more sensible.

Section 3., paragraph 3:
>    The following sections MUST be present in an Internet-Draft
>    containing a module:
>    o  Narrative sections
>    o  Definitions section
>    o  Security Considerations section
>    o  IANA Considerations section
>    o  References section

  I think it makes sense here to separate this into sections that this
  memo requires for YANG modules (the first two), and into sections that
  the general ID template requires (the final three), because the latter
  can change and obviously YANG IDs need new sections if they become
  required to submit an ID. For the latter, you should rephrase the
  sections that describe their content in a way that makes it clear that
  they are currently required, but that new ones may be added and just
  maybe some of the listed ones will dissappear.


Section 3.1., paragraph 3:
>    Each YANG module or submodule contained within an Internet-Draft or
>    RFC is considered to be a code component.  The strings '<CODE
>    BEGINS>' and '<CODE ENDS>' MUST be used to identify each code
>    component.

  I note that YANG is listed in
  http://trustee.ietf.org/license-info/archive/Code-Components-List-4-23-09.txt,
  so you actually do not need to require the use of <CODE BEGINS> and
  <CODE ENDS>.


Section 4., paragraph 1:
>    In general, modules in IETF standards-track specifications MUST
>    comply with all syntactic and semantic requirements of YANG.
>    [I-D.ietf-netmod-yang].  The guidelines in this section are intended
>    to supplement the YANG specification, which is intended to define a
>    minimum set of conformance requirements.

  You may want to recommend that authors verify the syntax of their YANG
  module with an automated checker every time before submitting a new
  revision. (I see that Section 4.8 talks about that - maybe add a
  forward reference?)


Section 4.5., paragraph 2:
>    The 'attribute' and 'namespace' axes are not supported in YANG, and
>    MAY be empty in a NETCONF server implementation.

  s/MAY/may/ (I don't think the idea is to make requirements on NETCONF
  servers here)


Section 6.1., paragraph 1:
>    transport is SSH [RFC4742].

  Reference missing: RFC4742

Support Russ' discuss.

Is there a yang doctors set up yet (like there was MIB doctors) where people send their modules to get reviewed?