On 10/26/2017 6:17 PM, Juergen Schoenwaelder wrote: > 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. context is everything: https://tools.ietf.org/html/draft-ietf-netmod-yang-tree-diagrams-02#section-3.2
As tree diagrams are intended to provide a simplified view of a module, diagrams longer than a page should generally be avoided. If the complete tree diagram for a module becomes too long, the diagram can be split into several smaller diagrams. For example, it might be possible to have one diagram with the data node and another with all notifications. If the data nodes tree is too long, it is also possible to split the diagram into smaller diagrams for different subtrees. 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. again, please suggest improvements. Lou > 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 > _______________________________________________ netmod mailing list netmod@ietf.org https://www.ietf.org/mailman/listinfo/netmod
