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

From: Joseph Gwinn <[email-masked]>
Date: Sat, 5 Nov 2016 16:54:00 -0400

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

---

From: Jiangyuanlong <[email-masked]>
Date: Mon, 7 Nov 2016 03:13:53 +0000

Hi Joe,

Thank you a lot for the thorough review. To resolve your comments, we will post an updated version after IETF 97 (when the submission of drafts is re-opened).

Cheers,
Yuanlong

-----Original Message-----
From: TICTOC [mailto:[email-masked]] On Behalf Of Joseph Gwinn
Sent: Sunday, November 06, 2016 4:54 AM
To: [email-masked]
Subject: [TICTOC] Comments on the proposed 1599v2 YANG model

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

---

From: Rodney Cummings <[email-masked]>
Date: Wed, 9 Nov 2016 20:39:42 +0000

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]."

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.

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?

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.

3. Regarding the second comment in A.4 (starting "As for the standard compliant").

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.

Rodney

> Sent: Saturday, November 5, 2016 3:54 PM
> To: [email-masked]

---

From: Joseph Gwinn <[email-masked]>
Date: Fri, 11 Nov 2016 09:16:40 -0500

Rodney,

On Wed, 9 Nov 2016 20:39:42 +0000, Rodney Cummings wrote:
> 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:
>
> 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.
> 

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.

> 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

---

From: Rodney Cummings <[email-masked]>
Date: Fri, 11 Nov 2016 23:22:27 +0000

Thanks Joe,

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

Rodney

> From: Joseph Gwinn [mailto:[email-masked]]
> Sent: Friday, November 11, 2016 8:17 AM
> To: Rodney Cummings <[email-masked]>
> Cc: [email-masked]
> Subject: RE: [TICTOC] Comments on the proposed 1599v2 YANG model
> 
> Rodney,
>

---

From: Greg Dowd <[email-masked]>
Date: Sat, 12 Nov 2016 02:00:18 +0000

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:[email-masked]] On Behalf Of Rodney Cummings
Sent: Friday, November 11, 2016 3:22 PM
To: Joseph Gwinn
Cc: [email-masked]
Subject: Re: [TICTOC] Comments on the proposed 1599v2 YANG model

EXTERNAL EMAIL

Thanks Joe,

Rodney

> > 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:
> >
> > Nevertheless, the summary does have the disadvantage of assuming 
> > that the reader is familiar with IEEE Std 1588-2008 specifications.
>
> If we expect that people will (must) first read and understand 1588, 
> we should say so right up front.
>
>
> 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.
>
> 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.
>
>
> > 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.
>
> > 3. Regarding the second comment in A.4 (starting "As for the 
> > standard [complaint]").
> >
> > YANG specifications and tutorials, and see if follow up discussion 
> > is needed.
>
> See prior answer.
>
> 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
> >

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

---

From: Jiangyuanlong <[email-masked]>
Date: Thu, 17 Nov 2016 07:35:58 +0000

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

> From: TICTOC [mailto:[email-masked]] On Behalf Of Greg Dowd
> Sent: Saturday, November 12, 2016 10:00 AM
> To: Rodney Cummings; Joseph Gwinn
> Cc: [email-masked]
> 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.
> 
> 
> 
> 
>