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

[Lou Berger <[e-mail]>]

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
>