Re: [TICTOC] Comments on the proposed 1599v2 YANG model

Hi Greg,

Thank you a lot for this alert, we will look into the texts and work closely with our WG chairs to avoid this issue.

Best regards,
Yuanlong

> -----Original Message-----
> From: TICTOC [mailto:tictoc-bounces@ietf.org] On Behalf Of Greg Dowd
> Sent: Saturday, November 12, 2016 10:00 AM
> To: Rodney Cummings; Joseph Gwinn
> Cc: tictoc@ietf.org
> Subject: Re: [TICTOC] Comments on the proposed 1599v2 YANG model
> 
> Our experiences with similar issues on the ptp-mib leads me to recommend
> that you use citation as much as possible as opposed to inclusion of relevant
> text.  Although we had permission to use from IEEE, IETF has not been
> willing to publish the mib specifically because of this single issue of
> attribution and copyright concern with respect to IEEE material.
> 
> 
> 
> 
> 
> -----Original Message-----
> From: TICTOC [mailto:tictoc-bounces@ietf.org] On Behalf Of Rodney
> Cummings
> Sent: Friday, November 11, 2016 3:22 PM
> To: Joseph Gwinn
> Cc: tictoc@ietf.org
> Subject: Re: [TICTOC] Comments on the proposed 1599v2 YANG model
> 
> EXTERNAL EMAIL
> 
> 
> Thanks Joe,
> 
> Helpful feedback... we'll make edits accordingly.
> 
> Rodney
> 
> > -----Original Message-----
> > From: Joseph Gwinn [mailto:joegwinn@comcast.net]
> > Sent: Friday, November 11, 2016 8:17 AM
> > To: Rodney Cummings <rodney.cummings@ni.com>
> > Cc: tictoc@ietf.org
> > Subject: RE: [TICTOC] Comments on the proposed 1599v2 YANG model
> >
> > Rodney,
> >
> > On Wed, 9 Nov 2016 20:39:42 +0000, Rodney Cummings wrote:
> > > Hi Joe,
> > >
> > > Thanks for the comments... very helpful.
> > >
> > > I'd like to discuss some high level themes for your comments.
> > >
> > > 1. Regarding comments on the leafs in the YANG module (section 3):
> > >
> > > As stated in the Introduction (section 1): "The data model is based
> > > on the PTP data sets as specified in [IEEE1588]."
> >
> > This is a bit too telegraphic, given the unspoken assumption that one
> > must read 1588-20xx before attempting to read YANG-1588.  More later.
> >
> >
> > > Therefore, each leaf is based on the normative specifications of
> > > clause 8 of IEEE Std 1588-2008. The name of each leaf aligns 1-1
> > > with the equivalent name of a 1588-2008 data set member. This YANG
> > > module can not change the 1588-2008 specifications. That means that
> > > the answer to most of your questions is:
> > >
> > >     Refer to the specifications in IEEE Std 1588-2008.
> > >
> > > For example, IEEE Std 1588-2008 specifies the units of measure for
> > > each leaf.
> > >
> > > That being said, the description of each leaf did make an attempt to
> > > summarize the specifications of IEEE Std 1588-2008. That methodology
> > > avoids the potential for a leaf description that is pages long.
> > > Nevertheless, the summary does have the disadvantage of assuming
> > > that the reader is familiar with IEEE Std 1588-2008 specifications.
> >
> > The unspoken assumption, now spoken.
> >
> > If we expect that people will (must) first read and understand 1588,
> > we should say so right up front.
> >
> >
> > > I suppose one could argue that each description should copy the text
> > > from IEEE Std 1588-2008 for each leaf, regardless of the length of
> > > that text.
> > >
> > > Is that what you are requesting?
> >
> > No.  The basic problem is that one cannot deduce from the YANG
> > document even a hint of your above explanation, which lack renders the
> > text of the YANG model document under review incomprehensible to
> > anyone not involved in the working groups.
> >
> > Now, one must write standards to be free-standing, understandable by
> > people who have never heard of a standards working group, or know
> > anybody who does either.
> >
> > So my specific suggestion is to add the above background information
> > to the document somewhere early in the document, so readers have the
> > full context and how it all fits together before they start reading
> > the core of YANG as applied to 1588, and so know where and how to find
> > the rest of the story.  Given the size of 1588, calling Clause 8 out
> > by name is quite helpful to the reader.
> >
> >
> > > 2. Regarding the first comment in A.4 (starting "Where is the
> > > specific make, model,").
> > >
> > > Again, this model and module is based on IEEE Std 1588-2008, and we
> > > explicitly avoid adding new features that are outside of that
> > > standard.
> > >
> > > There is a feature in the future IEEE 1588 revision that provides
> > > what you request, but since that 1588 revision is a
> > > work-in-progress, it is the subject of a future revision of this
> > > model/module (see bullet at top of page 4). The authors want to
> > > avoid creating a dependency between those two projects.
> >
> > See prior answer.
> >
> > We already have a very large dependency: one must read 1588 before
> > reading YANG-1588.  It later develops that one must also read RFC-6020.
> >
> >
> > > 3. Regarding the second comment in A.4 (starting "As for the
> > > standard [complaint]").
> > >
> > > YANG supports vendor-specific data through use of augments. There is
> > > no need to provide placeholders for such data. Please refer to the
> > > YANG specifications and tutorials, and see if follow up discussion
> > > is needed.
> >
> > See prior answer.
> >
> > In addition, the YANG specification (RFC-6020) is 173 pages long, and
> > the tutorials probably add up to a fair fraction of that, so a more
> > precise reference is needed.
> >
> > Most readers of YANG-1588 are not going to read RFC-6020 in any detail
> > until a significant need arise - it's too large and too complex for
> > casual reading.  Simple documents don't need tutorials.
> >
> >
> > Speaking of context, I found IEEE 1588-2008 impossible to follow in
> > any detail before I attended my first 1588 WG in Portsmouth, in
> > October 2016, and there witnessed the line-by-line edit we needed to
> > clarify the -2008 text for the coming -2017 version.  I submit that
> > there is a lesson in this.
> >
> > Thanks,
> >
> > Joe
> >
> >
> > > Rodney
> > >
> > >> -----Original Message-----
> > >> From: TICTOC [mailto:tictoc-bounces@ietf.org] On Behalf Of Joseph
> > >> Gwinn
> > >> Sent: Saturday, November 5, 2016 3:54 PM
> > >> To: tictoc@ietf.org
> > >> Subject: [TICTOC] Comments on the proposed 1599v2 YANG model
> > >>
> > >> To the TICTOC working group:
> > >>
> > >> Attached find my redlines against draft-ietf-tictoc-1588v2-yang-00
> > >> dated 20 October 2016.
> > >>
> > >> Where the arrows point should be text highlighted in yellow, but
> > >> the yellow may be faint in some readers.
> > >>
> > >> Joe Gwinn
> > >>
> > >
> 
> _______________________________________________
> TICTOC mailing list
> TICTOC@ietf.org
> https://www.ietf.org/mailman/listinfo/tictoc
> 
> _______________________________________________
> TICTOC mailing list
> TICTOC@ietf.org
> https://www.ietf.org/mailman/listinfo/tictoc