ietf
[Top] [All Lists]

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

2017-05-17 08:15:05
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
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.


.


<Prev in Thread] Current Thread [Next in Thread>