Document: draft-ietf-netconf-4741bis-07.txt
Reviewer: Brian Carpenter
Review Date: 2011-01-31
IETF LC End Date: 2011-02-07
IESG Telechat date: 

Summary: Almost ready - review use of normative words
--------

Comment:
--------

This is a 121 page document with a very large amount of code included,
including code explicitly marked as being normative content. I have
not checked this code in any way.

Minor issues
------------

I'm a little confused by some of the non-normative uses of lower case
"should".
For example:

"1.3.  Capabilities

   A NETCONF capability is a set of functionality that supplements the
   base NETCONF specification.  The capability is identified by a
   uniform resource identifier (URI).  These URIs should follow the
   guidelines as described in Section 8.
...
"8.  Capabilities

   This section defines a set of capabilities that a client or a server
   MAY implement."

So if the capabalities are a formal MAY, what is that apparently non-normative
"should" supposed to mean? I suggest that the sentence would be less confusing
if it said:

"Section 8 provides guidelines for these URIs." 

Another example:

"Appendix D.  Capability Template

   This non-normative section defines a template that should be used to
   define protocol capabilities. "

If it's non-normative, how is the reader to interpret "should"? Doesn't
it mean "could" or "might"?

There are tens of instances of lower case "should" and I wonder how many
of them are confusing in this way.

Similarly:

"2.3.  Authentication

   NETCONF connections must be authenticated.  "

Surely that should be normative MUST? And there are lots of other lower
case "must" and "may". The latter is especially confusing because in
examples like this:
"6.4.4.  Select All <name> Elements within the <users> Subtree

   This filter contains two containment nodes (<users>, <user>) and one
   selection node (<name>).  All instances of the <name> element in the
   same sibling set are selected in the filter output.  The client may
   need to know that <name> is used as an instance identifier..."

s/may/might/ would be appropriate, but in

"The filter element may optionally contain a "type" attribute."

s/may optionally/MAY/ would be appropriate.

The current mix of RFC 2119 terms, apparently normative lower case terms, and 
apparently non-normative use of "may" and "should" seems like it needs
cleaning up compared to RFC4741.