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

[Greg Dowd <[e-mail]>]

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:[e-mail]] On Behalf Of Rodney Cummings
Sent: Friday, November 11, 2016 3:22 PM
To: Joseph Gwinn
Cc: [e-mail]
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:[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
> >>
> >

_______________________________________________
TICTOC mailing list
[e-mail]
https://www.ietf.org/mailman/listinfo/tictoc