Please see attached review.
I am the assigned Gen-ART reviewer for this draft. For background on Gen-ART, please see the FAQ at <http://wiki.tools.ietf.org/area/gen/trac/wiki/GenArtfaq>. Please resolve these comments along with any other Last Call comments you may receive. 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.
_______________________________________________ Gen-art mailing list [email protected] https://www.ietf.org/mailman/listinfo/gen-art
