Re: [netmod] I-D Action: draft-ietf-netmod-yang-tree-diagrams-02.txt size

[Juergen Schoenwaelder <[e-mail]>]

On Fri, Oct 27, 2017 at 07:04:24AM -0400, Lou Berger wrote:
> 
> > We should encourage authors to split large diagrams into manageable
> > pieces. Sometimes suppressing lots of statistics counters helps,
> > sometimes showing which groupings are used instead of their expansion
> > helps. Sometimes it helps to separate major branches of a tree and to
> > discuss them separately. We should encourage authors to do these
> > things. 
> 
> I agree with this too, and this was the goal of the current text.
> > Perhaps we need to state clearly that it is not necessary to
> > include a plain fully expanded tree diagram.
> Please propose text for the draft!

Personally, I think usage guidelines do not belong into the yang tree
document in the first place. Having the document just define what tree
diagrams are would be my preference, leaving usage guidelines to our
guidelines document. Section 3.4 of 6087bis talks about tree diagrams
and I would prefer to have guidelines text in one place. But perhaps a
clear separation of 'here is stuff' from 'this is how we suggest to
use stuff' is difficult in practice. But what we have here is that we
now have two places where advice is given how to use stuff...

That said, RFC 6087bis says:

   YANG tree diagrams provide a concise representation of a YANG module,
   and SHOULD be included to help readers understand YANG module
   structure. Tree diagrams MAY be split into sections to correspond to
   document structure.

With all the capital letters in place, the text might cause people to
draw the wrong conclusion that they have to include plain tree
diagrams. The text does not give a good explanation when a split
should be considered or that a full plain dump may not be needed or
where to find good examples of diagrams broken into pieces. The text
in the yang tree diagram document is actually better in this regard.

The example in section 3.4 of RFC 6087bis is actually repeating the
non-NDMA /foo /foo-state style, well, we are getting off topic.
 
> > In the case of draft-ietf-teas-yang-te-topo-12.txt, the fully expanded
> > tree diagram (36 pages) is simply in no good relation with the size of
> > the definitions (47 pages). And the authors of this document do the
> > right thing, they provide overview diagrams that leave out lots of
> > details and that are comprehensible. So is it valuable to keep the
> > full dump in the document?
> I personally don't think so, and questioned its usefulness.  I also
> suggested moving to an appendix if they really wanted to keep it.  For
> whatever reason they decided they wanted to keep it which is, of course,
> within their purview.
> 
> So, I think the question for us is: what, beyond the change you suggest
> above, add to the tree draft to cover cases where authors really want to
> include such long trees?

At the end, WGs decide with the input from the authors, reviewers
etc. and not everything needs to have rules that we cast into RFCs.
Perhaps we are better off having a few questions and answers on the
FAQ concerning tree diagrams.

/js

-- 
Juergen Schoenwaelder           Jacobs University Bremen gGmbH
Phone: [phone]         Campus Ring 1 | 28759 Bremen | Germany
Fax:   [phone]         <http://www.jacobs-university.de/>