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

[Lou Berger <[e-mail]>]

On October 27, 2017 3:44:39 AM Martin Bjorklund <[e-mail]> wrote:

> Robert Wilton <[e-mail]> wrote:
>>
>>
>> On 26/10/2017 17:50, t.petch wrote:
>> > Lou
>> >
>> > I like the advice that diagrams should be one page long but wonder how
>> > to apply that to those I see in routing WGs.  I have just been looking
>> > at
>> >
>> >   draft-ietf-teas-yang-te-topo-12
>> >
>> > where the diagram is 36 pages long - which may be one of the larger
>> > ones
>> > but by no means exceptional - and I think the diagram is  more or less
>> > useless as a result.  But what practical advice can we give them?
>> 36 pages!  Wow.  It should be split up into smaller chunks, at that
>> size I suspect that there is a certain amount of repetition.
>
> Right.  I think we need to think about *why* we include these tree
> diagrams in the first place, so that it doesn't just become a checkbox
> item for draft authors.  The original idea behind including the tree
> diagrams was to give the reader an *overview* of the structure of the
> model.   If the tree becomes too large, it obviously doesn't help
> anymore.  So what do you do in this case?  I think there are a couple
> of things you can do:
>
>   o split the diagram into smaller pieces, and explain each piece on
>     its own (see e.g. RFC 7317).
>
>   o make use of "..." to show the overall structure w/o all the
>     details.  (pyang --tree-depth might help here)
>
>   o introduce the option of not expanding groupings, as was proposed
>     earlier.
>
> I'd rather see a small diagram that explains the structure, but
> leaves out the details (they are of course found the module), than a
> 36-page long figure that can't really be read.
>

I completely agree,  but also think we need to cover (okay, protect 
ourselves from) the case of full trees included in drafts.

Lou

>
> /martin
>