Document: draft-ietf-netmod-yang-usage-07
Reviewer: Enrico Marocco
Review Date: July 9, 2010
IETF LC End Date: July 8, 2010

Note: This review comes one day after the LC End Date, my bad. I'm
sending it anyways, hoping it may be useful in the reminder of the
publishing process. Feel free to ignore my late comments.


Summary: This draft is on the right track but has open issues, described
in the review.


Major Issues:

None.


Minor Issues:

Some guidelines in the document point to documents on the web that
cannot be assumed to stay stable for as long as the RFC. My advice is to
replace them with more stable references, or with new text in the
document itself. In particular:

S. 3. "General Documentation Guidelines:" replace the URL pointing to
rfc-editor.org with references to RFC 2223. The first paragraph could be
rewritten as:

OLD:
   YANG data model modules under review are likely to be contained in
   Internet-Drafts.  All guidelines for Internet-Draft authors MUST be
   followed.  These guidelines are available online at:

   http://www.rfc-editor.org/rfc-editor/instructions2authors.txt

NEW:
   YANG data model modules under review are likely to be contained in
   Internet-Drafts, formatted according to RFC 2223 [ref to the RFC]
   and its successors.

S. 3.4. "Security Considerations Section," first paragraph: is there
really a need to define such a template in an external document (that
most likely won't be reachable in a few years at the given URL)? Why not
simply putting the whole template (< 2pg) in this document? [Note that
the same document is also referenced in the draft's "Security
Considerations" section.]


Nits:

Abstract: expand NETCONF (as per
http://www.rfc-editor.org/rfc-style-guide/abbrev.expansion.txt) and
provide a few words about YANG for the casual reader.

S. 3.3. "Definitions Section," first para: define "YIN."

S. 3.4. "Security Considerations Section," third bullet point: s/'rpc'
statements/YANG 'rpc' statements/

S. 3.5.1. "Documents that Create a New Name Space," second para: here
citing I-D.ietf-netmod-yang after "The YANG specification" may help the
reader.

S. 4.1 "Module Naming Conventions," third para: as I understand, an IANA
registry is going to guarantee name uniqueness. Why not mentioning it
here (other than in S. 4.7)?

S. 4.4. "Conditional Statements," third para: s/indicate the/indicate
that the/

S. 4.5. "XPath Usage," fourth para: quote the node properties provided
as an example. Before that point names/variables are quoted.

S. 4.5. "XPath Usage," seventh para: quotes in the example again.

S. 4.7. "Module Header, Meta, and Revision Statements," second para:
s/documented/document/

S. 4.10. "Data Types:" quote "identityref," "int32," "enum" and "bit."