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

Lou Berger <lberger@labn.net> Fri, 27 October 2017 10:06 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 C620E13A9F5 for <netmod@ietfa.amsl.com>; Fri, 27 Oct 2017 03:06:12 -0700 (PDT)
X-Virus-Scanned: amavisd-new at amsl.com
X-Spam-Flag: NO
X-Spam-Score: -4.201
X-Spam-Level:
X-Spam-Status: No, score=-4.201 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, RCVD_IN_SORBS_SPAM=0.5, SPF_PASS=-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 Ya_X4P1IMiHi for <netmod@ietfa.amsl.com>; Fri, 27 Oct 2017 03:06:11 -0700 (PDT)
Received: from gproxy2-pub.mail.unifiedlayer.com (gproxy2-pub.mail.unifiedlayer.com [69.89.18.3]) (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 7BB5013B13B for <netmod@ietf.org>; Fri, 27 Oct 2017 03:06:11 -0700 (PDT)
Received: from CMOut01 (unknown [10.0.90.82]) by gproxy2.mail.unifiedlayer.com (Postfix) with ESMTP id 2A37B1E09F1 for <netmod@ietf.org>; Fri, 27 Oct 2017 04:06:08 -0600 (MDT)
Received: from box313.bluehost.com ([69.89.31.113]) by CMOut01 with id Sa641w01E2SSUrH01a679V; Fri, 27 Oct 2017 04:06:08 -0600
X-Authority-Analysis: v=2.2 cv=K4VSJ2eI c=1 sm=1 tr=0 a=h1BC+oY+fLhyFmnTBx92Jg==:117 a=h1BC+oY+fLhyFmnTBx92Jg==:17 a=IkcTkHD0fZMA:10 a=02M-m0pO-4AA:10 a=u07AKapRAAAA:8 a=AUd_NHdVAAAA:8 a=y6juYkxV1VpOikQJWNEA:9 a=QEXdDO2ut3YA:10 a=SkebfZ6J2Mmvk2rLHZle: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:MIME-Version:Subject: References:In-Reply-To:Message-ID:Date:CC:To:From:Sender:Reply-To: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=2F8x7QqmJlob5bKPAsbkVqT7xTPU3VT8P/GqeDchA/I=; b=bLoKJlQHPnxW6wLVYRCvklMG2v NtODfGfdwFxVyPKeV/6IbGML4yUbbC3Xelp3zRCQ5bru2lhAi+withvUgdDkQgjyVSeOJBOny0hDG 4GCmeQ7Kn2+Cl2N+EyrUAq9zr;
Received: from pool-100-15-86-101.washdc.fios.verizon.net ([100.15.86.101]:54156 helo=[11.4.0.163]) by box313.bluehost.com with esmtpsa (TLSv1.2:ECDHE-RSA-AES128-GCM-SHA256:128) (Exim 4.87) (envelope-from <lberger@labn.net>) id 1e81We-000IZz-6x; Fri, 27 Oct 2017 04:06:04 -0600
From: Lou Berger <lberger@labn.net>
To: Martin Bjorklund <mbj@tail-f.com>, <rwilton@cisco.com>
CC: <ietfc@btconnect.com>, <netmod@ietf.org>
Date: Fri, 27 Oct 2017 06:06:02 -0400
Message-ID: <15f5d4baf10.27d3.9b4188e636579690ba6c69f2c8a0f1fd@labn.net>
In-Reply-To: <20171027.094405.1477743471980617736.mbj@tail-f.com>
References: <23892572-a0db-d24b-e591-a19799ace9ae@labn.net> <010301d34e7b$1d5303c0$4001a8c0@gateway.2wire.net> <7f3b7f56-2de2-62c2-f9ec-6a010348eeb9@cisco.com> <20171027.094405.1477743471980617736.mbj@tail-f.com>
User-Agent: AquaMail/1.11.0-568 (build: 101100004)
MIME-Version: 1.0
Content-Type: text/plain; format=flowed; charset="UTF-8"
Content-Transfer-Encoding: 8bit
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: 1e81We-000IZz-6x
X-Source:
X-Source-Args:
X-Source-Dir:
X-Source-Sender: pool-100-15-86-101.washdc.fios.verizon.net ([11.4.0.163]) [100.15.86.101]:54156
X-Source-Auth: lberger@labn.net
X-Email-Count: 4
X-Source-Cap: bGFibm1vYmk7bGFibm1vYmk7Ym94MzEzLmJsdWVob3N0LmNvbQ==
X-Local-Domain: yes
Archived-At: <https://mailarchive.ietf.org/arch/msg/netmod/MEjs3KCw9O2q3wBIv9uGDVMFalU>
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: Fri, 27 Oct 2017 10:06:13 -0000


On October 27, 2017 3:44:39 AM Martin Bjorklund <mbj@tail-f.com> wrote:

> Robert Wilton <rwilton@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
>