Subject: Genart last call review of draft-ietf-netmod-yang-model-classification-06

From: Pete Resnick <[email-masked]>
Date: Tue, 09 May 2017 23:03:01 -0700

Reviewer: Pete Resnick
Review result: Ready with Issues

I am the assigned Gen-ART reviewer for this draft. The General Area
Review Team (Gen-ART) reviews all IETF documents being processed
by the IESG for the IETF Chair.  Please treat these comments just
like any other last call comments.

For more information, please see the FAQ at

<https://trac.ietf.org/trac/gen/wiki/GenArtfaq>.

Document: draft-ietf-netmod-yang-model-classification-??
Reviewer: Pete Resnick
Review Date: 2017-05-09
IETF LC End Date: 2017-05-14
IESG Telechat date: Not scheduled for a telechat

Summary: Ready with Minor Issues/Nits

To an outsider like me, this seems like a useful document and it was
an interesting read. The document could use a serious edit for grammar
and typos. A few specific comments below.

Major issues: None.

Minor issues:

In section 2.1, paragraphs 4 and 5 mention "speed". The speed of what?
Development of the module? It's not clear from the text.

In section 3.1, it says:

                          While there is no formal definition of what
   construes an SDO, a common feature is that they publish
   specifications along specific processes with content that reflects
   some sort of membership consensus.  The specifications are
developed
   for wide use among the membership or for audiences beyond that.
   
First of all, s/construes/constitutes. But aside from that, it's not
at all clear to me that a common feature is "membership consensus".
For example, we don't have membership, and many other organizations
use voting and not consensus. Perhaps replace the above with something
simpler like:

                          Most SDOs create specifications according
to
   a formal process in order to produce a standard that is useful for
   their constituencies.

Nits/editorial comments:

In the Abstract and section 3.1, you use "standards-defining
organization" for SDO. I've never heard that phrase used before.
Elsewhere in the document, you use "standards development
organization", which is the phrase I've always seen used. I suggest
you change to that in both places.

Throughout the document, you say things like, "the authors believe" or
"we assume". This is a WG consensus document. While I generally think
that using these terms is bad form in a WG document, saying "the
authors believe" almost sounds like the authors believe it, but the WG
might not. If the authors and the WG believe XYZ, don't say "the
authors believe XYZ" or "we believe XYZ"; just say "XYZ", or at least
use the passive voice. So:

Section 1:

OLD
   The intent of this document is to provide a taxonomy to simplify
   human communication around YANG modules.  The authors acknowledge
   that the classification boundaries are at times blurry, but
believe
   that this document should provide a robust starting point as the
YANG
   community gains further experience with designing and deploying
   modules.  To be more explicit, the authors believe that the
   classification criteria will change over time.
NEW
   The intent of this document is to provide a taxonomy to simplify
   human communication around YANG modules.  While the classification
   boundaries are at times blurry, this document should provide a
robust
   starting point as the YANG community gains further experience with
   designing and deploying modules.  To be more explicit, it is
expected
   that the classification criteria will change over time.
END

Section 2:

OLD
                                                     For the purpose
of
   this document we assume that both approaches (bottom-up and
top-down)
   will be used as they both provide benefits that appeal to
different
   groups.
NEW
                                                     This document
   considers both bottom-up and top-down approaches as they are both
used
   and they each provide benefits that appeal to different groups.
END

Section 2.1:

OLD
                                                     For the purpose
of
   this document we will use the term "orchestrator" to describe a
   system implementing such a process.
NEW
                                                     For the purpose
of
   this document, the term "orchestrator" is used to describe a
system
   implementing such a process.

Section 2.2:

OLD
   Although the [RFC7950], [RFC7950] doesn't explain the relationship
of
   the terms '(YANG) data model' and '(YANG) module', the authors
   understand there is a 1:1 relationship between a data model and a
   YANG module, but a data model may also be expressed using a
   collection of YANG modules (and submodules).

(This one's not even grammatical. Here's my best guess as to what you
meant)

NEW
   Although [RFC7950] doesn't explain the relationship between the
terms
   '(YANG) data model' and '(YANG) module', there is a 1:1
relationship
   between a data model and a YANG module. However, a data model may
   also be expressed using a collection of YANG modules (and
submodules).
   
That's it for all of the "author" and "we" items. One other nit:

3.2 s/augmented into/added into. I don't think you can "augment into"
something.

---

From: Benoit Claise <[email-masked]>
Date: Wed, 17 May 2017 09:14:40 -0400

Thanks Pete,

Version 7 has been posted.
All your feedback has been taken into account.
https://www.ietf.org/rfcdiff?url2=draft-ietf-netmod-yang-model-classification-07

Regards, Benoit
> .