On October 27, 2017 3:44:39 AM Martin Bjorklund <m...@tail-f.com> wrote:
Robert Wilton <rwil...@cisco.com> 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
_______________________________________________
netmod mailing list
netmod@ietf.org
https://www.ietf.org/mailman/listinfo/netmod
