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

Martin Bjorklund <mbj@tail-f.com> Fri, 27 October 2017 07:44 UTC

Return-Path: <mbj@tail-f.com>
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 47CAC139982 for <netmod@ietfa.amsl.com>; Fri, 27 Oct 2017 00:44:09 -0700 (PDT)
X-Virus-Scanned: amavisd-new at amsl.com
X-Spam-Flag: NO
X-Spam-Score: -1.901
X-Spam-Level:
X-Spam-Status: No, score=-1.901 tagged_above=-999 required=5 tests=[BAYES_00=-1.9, SPF_PASS=-0.001] autolearn=ham autolearn_force=no
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 HID4Qs7DOGYk for <netmod@ietfa.amsl.com>; Fri, 27 Oct 2017 00:44:08 -0700 (PDT)
Received: from mail.tail-f.com (mail.tail-f.com [46.21.102.45]) by ietfa.amsl.com (Postfix) with ESMTP id D1417138FA0 for <netmod@ietf.org>; Fri, 27 Oct 2017 00:44:07 -0700 (PDT)
Received: from localhost (h-40-225.A165.priv.bahnhof.se [94.254.40.225]) by mail.tail-f.com (Postfix) with ESMTPSA id 21A831AE030A; Fri, 27 Oct 2017 09:44:06 +0200 (CEST)
Date: Fri, 27 Oct 2017 09:44:05 +0200 (CEST)
Message-Id: <20171027.094405.1477743471980617736.mbj@tail-f.com>
To: rwilton@cisco.com
Cc: ietfc@btconnect.com, netmod@ietf.org, lberger@labn.net
From: Martin Bjorklund <mbj@tail-f.com>
In-Reply-To: <7f3b7f56-2de2-62c2-f9ec-6a010348eeb9@cisco.com>
References: <23892572-a0db-d24b-e591-a19799ace9ae@labn.net> <010301d34e7b$1d5303c0$4001a8c0@gateway.2wire.net> <7f3b7f56-2de2-62c2-f9ec-6a010348eeb9@cisco.com>
X-Mailer: Mew version 6.7 on Emacs 24.5 / Mule 6.0 (HANACHIRUSATO)
Mime-Version: 1.0
Content-Type: Text/Plain; charset=iso-8859-1
Content-Transfer-Encoding: quoted-printable
Archived-At: <https://mailarchive.ietf.org/arch/msg/netmod/hX1PzABpxTg0LpjDFp9TVUjYC4o>
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 07:44:09 -0000

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.


/martin