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

Juergen Schoenwaelder <j.schoenwaelder@jacobs-university.de> Thu, 26 October 2017 22:19 UTC

Return-Path: <j.schoenwaelder@jacobs-university.de>
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 BFF2513F605 for <netmod@ietfa.amsl.com>; Thu, 26 Oct 2017 15:19:06 -0700 (PDT)
X-Virus-Scanned: amavisd-new at amsl.com
X-Spam-Flag: NO
X-Spam-Score: -1.899
X-Spam-Level:
X-Spam-Status: No, score=-1.899 tagged_above=-999 required=5 tests=[BAYES_00=-1.9, RCVD_IN_DNSWL_NONE=-0.0001, URIBL_BLOCKED=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 UCFyNasBUywk for <netmod@ietfa.amsl.com>; Thu, 26 Oct 2017 15:19:04 -0700 (PDT)
Received: from atlas5.jacobs-university.de (atlas5.jacobs-university.de [212.201.44.20]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by ietfa.amsl.com (Postfix) with ESMTPS id 7B27A13F46E for <netmod@ietf.org>; Thu, 26 Oct 2017 15:19:04 -0700 (PDT)
Received: from localhost (demetrius5.irc-it.jacobs-university.de [10.70.0.222]) by atlas5.jacobs-university.de (Postfix) with ESMTP id 2310EEFF; Fri, 27 Oct 2017 00:19:03 +0200 (CEST)
X-Virus-Scanned: amavisd-new at jacobs-university.de
Received: from atlas5.jacobs-university.de ([10.70.0.217]) by localhost (demetrius5.jacobs-university.de [10.70.0.222]) (amavisd-new, port 10032) with ESMTP id stJuLGVFJH19; Fri, 27 Oct 2017 00:19:02 +0200 (CEST)
Received: from hermes.jacobs-university.de (hermes.jacobs-university.de [212.201.44.23]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (Client CN "hermes.jacobs-university.de", Issuer "Jacobs University CA - G01" (verified OK)) by atlas5.jacobs-university.de (Postfix) with ESMTPS; Fri, 27 Oct 2017 00:19:02 +0200 (CEST)
Received: from localhost (demetrius4.jacobs-university.de [212.201.44.49]) by hermes.jacobs-university.de (Postfix) with ESMTP id E5C272010B; Fri, 27 Oct 2017 00:19:02 +0200 (CEST)
X-Virus-Scanned: amavisd-new at jacobs-university.de
Received: from hermes.jacobs-university.de ([212.201.44.23]) by localhost (demetrius4.jacobs-university.de [212.201.44.32]) (amavisd-new, port 10024) with ESMTP id 6xf48g7ST-Cr; Fri, 27 Oct 2017 00:19:02 +0200 (CEST)
Received: from elstar.local (elstar.jacobs.jacobs-university.de [10.50.231.133]) by hermes.jacobs-university.de (Postfix) with ESMTP id 6BE042010A; Fri, 27 Oct 2017 00:19:02 +0200 (CEST)
Received: by elstar.local (Postfix, from userid 501) id B2AC7413EC4C; Fri, 27 Oct 2017 00:17:36 +0200 (CEST)
Date: Fri, 27 Oct 2017 00:17:36 +0200
From: Juergen Schoenwaelder <j.schoenwaelder@jacobs-university.de>
To: Lou Berger <lberger@labn.net>
Cc: "t.petch" <ietfc@btconnect.com>, netmod@ietf.org
Message-ID: <20171026221736.cl3kpzo2i7zaa4qh@elstar.local>
Reply-To: Juergen Schoenwaelder <j.schoenwaelder@jacobs-university.de>
Mail-Followup-To: Lou Berger <lberger@labn.net>, "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>
MIME-Version: 1.0
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
In-Reply-To: <d592e9c4-21c8-16d5-a0a9-f6ce54cd31da@labn.net>
User-Agent: NeoMutt/20170714 (1.8.3)
Archived-At: <https://mailarchive.ietf.org/arch/msg/netmod/PkIUL8qDM7Lw3bTHyGSW8TkBm9k>
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 22:19:07 -0000

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.

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

-- 
Juergen Schoenwaelder           Jacobs University Bremen gGmbH
Phone: +49 421 200 3587         Campus Ring 1 | 28759 Bremen | Germany
Fax:   +49 421 200 3103         <http://www.jacobs-university.de/>