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

[Juergen Schoenwaelder <[e-mail]>]

On Thu, Oct 26, 2017 at 01:32:45PM -0400, Lou Berger wrote:
 
> > But what practical advice can we give them?
> 
> we added section 3.2 covering Long Diagrams in general, and due to this
> draft we added:
> 
>    When long diagrams are included in a document, authors
>    should consider whether to include the long diagram in the main body
>    of the document or in an appendix.
> 
> This is also the recommendation I made to the authors as that draft's
> Shepherd...
> 
> If you have any suggestion on improving the language that would be most
> appreciated.

I think the suggestion is wrong. A long tree diagram should be split
into smaller meaningful pieces to help readers. Moving the diagram to
a different place in the document does not really achieve anything.

I love the way RFC 7317 is written. Sure, the model in RFC 7317 is not
as complex as some of the newer models but still breaking things into
pieces that are explained with surrounding text is where you get a lot
of added value. Yes, there is real work to be done to produce such a
document but as a reader or reviewer or implementor it helps
tremendously with understanding the model if things are presented in
digestable pieces.

/js

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