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

[Joseph Gwinn <[e-mail]>]

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
>> 
>