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

[Lou Berger <[e-mail]>]

On 10/27/2017 6:51 AM, Juergen Schoenwaelder wrote:
> On Fri, Oct 27, 2017 at 06:00:50AM -0400, Lou Berger wrote:
>> Juergen,
>>
>> Keep in mind this is guidance, so autos may include a long tree even if the
>> text says don't.  So what do you want them to do if they decide they really
>> want a many page tree? leave the long tree in the body???
>>
> What I am saying is that the value of the diagram does not change if I
> move it around. If a plain fully expanded tree dump is not useful
> anymore for the reader to get an overview, then other content must be
> produced to provide an overview.  And perhaps the plain tree dump is
> then not even needed anymore to be present in the document if there is
> other good overview material.
I completely agree.

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

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

Lou
> /js
>