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

[Rodney Cummings <[e-mail]>]

Thanks Joe,

Helpful feedback... we'll make edits accordingly.

Rodney

> -----Original Message-----
> From: Joseph Gwinn [mailto:[e-mail]]
> Sent: Friday, November 11, 2016 8:17 AM
> To: Rodney Cummings <[e-mail]>
> Cc: [e-mail]
> 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:[e-mail]] On Behalf Of Joseph Gwinn
> >> Sent: Saturday, November 5, 2016 3:54 PM
> >> To: [e-mail]
> >> 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
> >>
> >