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

Lou Berger <lberger@labn.net> Thu, 26 October 2017 23:03 UTC

Return-Path: <lberger@labn.net>
X-Original-To: netmod@ietfa.amsl.com
Delivered-To: netmod@ietfa.amsl.com
Received: from localhost (localhost [127.0.0.1]) by ietfa.amsl.com (Postfix) with ESMTP id 2CB0713A296 for <netmod@ietfa.amsl.com>; Thu, 26 Oct 2017 16:03:24 -0700 (PDT)
X-Virus-Scanned: amavisd-new at amsl.com
X-Spam-Flag: NO
X-Spam-Score: -4.7
X-Spam-Level:
X-Spam-Status: No, score=-4.7 tagged_above=-999 required=5 tests=[BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, RCVD_IN_MSPIKE_H2=-2.8, SPF_PASS=-0.001, URIBL_BLOCKED=0.001] autolearn=ham autolearn_force=no
Authentication-Results: ietfa.amsl.com (amavisd-new); dkim=pass (768-bit key) header.d=labn.net
Received: from mail.ietf.org ([4.31.198.44]) by localhost (ietfa.amsl.com [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id pAulJkFwNeq6 for <netmod@ietfa.amsl.com>; Thu, 26 Oct 2017 16:03:22 -0700 (PDT)
Received: from gproxy6-pub.mail.unifiedlayer.com (gproxy6-pub.mail.unifiedlayer.com [67.222.39.168]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by ietfa.amsl.com (Postfix) with ESMTPS id 675E9139F44 for <netmod@ietf.org>; Thu, 26 Oct 2017 16:03:22 -0700 (PDT)
Received: from cmgw2 (unknown [10.0.90.83]) by gproxy6.mail.unifiedlayer.com (Postfix) with ESMTP id 3DC9A1E063A for <netmod@ietf.org>; Thu, 26 Oct 2017 17:03:20 -0600 (MDT)
Received: from box313.bluehost.com ([69.89.31.113]) by cmgw2 with id SP3G1w00Y2SSUrH01P3Kpe; Thu, 26 Oct 2017 17:03:20 -0600
X-Authority-Analysis: v=2.2 cv=dZfw5Tfe c=1 sm=1 tr=0 a=h1BC+oY+fLhyFmnTBx92Jg==:117 a=h1BC+oY+fLhyFmnTBx92Jg==:17 a=IkcTkHD0fZMA:10 a=xqWC_Br6kY4A:10 a=02M-m0pO-4AA:10 a=48vgC7mUAAAA:8 a=qLRM_7iknmYyy--agnkA:9 a=QEXdDO2ut3YA:10 a=w1C3t2QeGrPiZgrLijVG:22
DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=labn.net; s=default; h=Content-Transfer-Encoding:Content-Type:In-Reply-To:MIME-Version :Date:Message-ID:From:References:To:Subject:Sender:Reply-To:Cc:Content-ID: Content-Description:Resent-Date:Resent-From:Resent-Sender:Resent-To:Resent-Cc :Resent-Message-ID:List-Id:List-Help:List-Unsubscribe:List-Subscribe: List-Post:List-Owner:List-Archive; bh=DQKfjcfO/JZkhwBIT4xSiRvJjZSKW1I6wTooRmNaqbw=; b=vAv4uCdoPQLpWcdgp/wA6PPjyx EDPZpWBNiZJ6pxSYbkHp43+VRUnr7mCLZwpNkeatxGDGqObNTE4je4OBiinr5yivEkqUKcxcMtcPr oBAPEgMifsy12mHGgflqO1Skv;
Received: from pool-100-15-86-101.washdc.fios.verizon.net ([100.15.86.101]:42874 helo=[IPv6:::1]) by box313.bluehost.com with esmtpsa (TLSv1.2:ECDHE-RSA-AES128-GCM-SHA256:128) (Exim 4.87) (envelope-from <lberger@labn.net>) id 1e7rBE-002DOV-Ee; Thu, 26 Oct 2017 17:03:16 -0600
To: "t.petch" <ietfc@btconnect.com>, netmod@ietf.org
References: <150893578927.4882.2117597388624976982@ietfa.amsl.com> <23892572-a0db-d24b-e591-a19799ace9ae@labn.net> <010301d34e7b$1d5303c0$4001a8c0@gateway.2wire.net> <d592e9c4-21c8-16d5-a0a9-f6ce54cd31da@labn.net> <20171026221736.cl3kpzo2i7zaa4qh@elstar.local>
From: Lou Berger <lberger@labn.net>
Message-ID: <3cb344fe-2d49-3fd1-90ad-e6ffe0734dc7@labn.net>
Date: Thu, 26 Oct 2017 19:03:11 -0400
User-Agent: Mozilla/5.0 (Windows NT 10.0; WOW64; rv:52.0) Gecko/20100101 Thunderbird/52.4.0
MIME-Version: 1.0
In-Reply-To: <20171026221736.cl3kpzo2i7zaa4qh@elstar.local>
Content-Type: text/plain; charset=utf-8
Content-Transfer-Encoding: 7bit
Content-Language: en-US
X-AntiAbuse: This header was added to track abuse, please include it with any abuse report
X-AntiAbuse: Primary Hostname - box313.bluehost.com
X-AntiAbuse: Original Domain - ietf.org
X-AntiAbuse: Originator/Caller UID/GID - [47 12] / [47 12]
X-AntiAbuse: Sender Address Domain - labn.net
X-BWhitelist: no
X-Source-IP: 100.15.86.101
X-Exim-ID: 1e7rBE-002DOV-Ee
X-Source:
X-Source-Args:
X-Source-Dir:
X-Source-Sender: pool-100-15-86-101.washdc.fios.verizon.net ([IPv6:::1]) [100.15.86.101]:42874
X-Source-Auth: lberger@labn.net
X-Email-Count: 2
X-Source-Cap: bGFibm1vYmk7bGFibm1vYmk7Ym94MzEzLmJsdWVob3N0LmNvbQ==
X-Local-Domain: yes
Archived-At: <https://mailarchive.ietf.org/arch/msg/netmod/KrUIuTu0TGUdpGQxPKcDMNW6d64>
Subject: Re: [netmod] I-D Action: draft-ietf-netmod-yang-tree-diagrams-02.txt size
X-BeenThere: netmod@ietf.org
X-Mailman-Version: 2.1.22
Precedence: list
List-Id: NETMOD WG list <netmod.ietf.org>
List-Unsubscribe: <https://www.ietf.org/mailman/options/netmod>, <mailto:netmod-request@ietf.org?subject=unsubscribe>
List-Archive: <https://mailarchive.ietf.org/arch/browse/netmod/>
List-Post: <mailto:netmod@ietf.org>
List-Help: <mailto:netmod-request@ietf.org?subject=help>
List-Subscribe: <https://www.ietf.org/mailman/listinfo/netmod>, <mailto:netmod-request@ietf.org?subject=subscribe>
X-List-Received-Date: Thu, 26 Oct 2017 23:03:24 -0000


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
>