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

Juergen Schoenwaelder <j.schoenwaelder@jacobs-university.de> Fri, 27 October 2017 11:58 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 E9BF413F501 for <netmod@ietfa.amsl.com>; Fri, 27 Oct 2017 04:58:29 -0700 (PDT)
X-Virus-Scanned: amavisd-new at amsl.com
X-Spam-Flag: NO
X-Spam-Score: -1.9
X-Spam-Level:
X-Spam-Status: No, score=-1.9 tagged_above=-999 required=5 tests=[BAYES_00=-1.9, RCVD_IN_DNSWL_NONE=-0.0001] 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 vKbXHPsiSm1L for <netmod@ietfa.amsl.com>; Fri, 27 Oct 2017 04:58:28 -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 EBBE513B13E for <netmod@ietf.org>; Fri, 27 Oct 2017 04:58:27 -0700 (PDT)
Received: from localhost (demetrius5.irc-it.jacobs-university.de [10.70.0.222]) by atlas5.jacobs-university.de (Postfix) with ESMTP id BB46A373; Fri, 27 Oct 2017 13:58:26 +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 gHiqivxxD0vC; Fri, 27 Oct 2017 13:58:25 +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 13:58:26 +0200 (CEST)
Received: from localhost (demetrius3.jacobs-university.de [212.201.44.48]) by hermes.jacobs-university.de (Postfix) with ESMTP id A7F902010B; Fri, 27 Oct 2017 13:58:26 +0200 (CEST)
X-Virus-Scanned: amavisd-new at jacobs-university.de
Received: from hermes.jacobs-university.de ([212.201.44.23]) by localhost (demetrius3.jacobs-university.de [212.201.44.32]) (amavisd-new, port 10024) with ESMTP id KpmyWV_nkNO0; Fri, 27 Oct 2017 13:58:25 +0200 (CEST)
Received: from elstar.local (elstar.jacobs.jacobs-university.de [10.50.231.133]) by hermes.jacobs-university.de (Postfix) with ESMTP id 192942010A; Fri, 27 Oct 2017 13:58:26 +0200 (CEST)
Received: by elstar.local (Postfix, from userid 501) id 69961413FA46; Fri, 27 Oct 2017 13:57:00 +0200 (CEST)
Date: Fri, 27 Oct 2017 13:57:00 +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: <20171027115700.u5xwq5xw347jbclp@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> <20171026221736.cl3kpzo2i7zaa4qh@elstar.local> <3cb344fe-2d49-3fd1-90ad-e6ffe0734dc7@labn.net> <20171026234123.pt65l6ctgmx2hd55@elstar.local> <15f5d46ec50.27d3.9b4188e636579690ba6c69f2c8a0f1fd@labn.net> <20171027105159.up6ec5xwbcy75hcr@elstar.local> <34dbaaaa-8a06-f980-7bf8-4a54aa117423@labn.net>
MIME-Version: 1.0
Content-Type: text/plain; charset=iso-8859-1
Content-Disposition: inline
X-Clacks-Overhead: GNU Terry Pratchett
Content-Transfer-Encoding: 8bit
In-Reply-To: <34dbaaaa-8a06-f980-7bf8-4a54aa117423@labn.net>
User-Agent: NeoMutt/20170714 (1.8.3)
Archived-At: <https://mailarchive.ietf.org/arch/msg/netmod/Rij4CXec82_S0XV7d5AHfDJP4ss>
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 11:58:30 -0000

On Fri, Oct 27, 2017 at 07:04:24AM -0400, Lou Berger wrote:
> 
> > We should encourage authors to split large diagrams into manageable
> > pieces. Sometimes suppressing lots of statistics counters helps,
> > sometimes showing which groupings are used instead of their expansion
> > helps. Sometimes it helps to separate major branches of a tree and to
> > discuss them separately. We should encourage authors to do these
> > things. 
> 
> I agree with this too, and this was the goal of the current text.
> > Perhaps we need to state clearly that it is not necessary to
> > include a plain fully expanded tree diagram.
> Please propose text for the draft!

Personally, I think usage guidelines do not belong into the yang tree
document in the first place. Having the document just define what tree
diagrams are would be my preference, leaving usage guidelines to our
guidelines document. Section 3.4 of 6087bis talks about tree diagrams
and I would prefer to have guidelines text in one place. But perhaps a
clear separation of 'here is stuff' from 'this is how we suggest to
use stuff' is difficult in practice. But what we have here is that we
now have two places where advice is given how to use stuff...

That said, RFC 6087bis says:

   YANG tree diagrams provide a concise representation of a YANG module,
   and SHOULD be included to help readers understand YANG module
   structure. Tree diagrams MAY be split into sections to correspond to
   document structure.

With all the capital letters in place, the text might cause people to
draw the wrong conclusion that they have to include plain tree
diagrams. The text does not give a good explanation when a split
should be considered or that a full plain dump may not be needed or
where to find good examples of diagrams broken into pieces. The text
in the yang tree diagram document is actually better in this regard.

The example in section 3.4 of RFC 6087bis is actually repeating the
non-NDMA /foo /foo-state style, well, we are getting off topic.
 
> > In the case of draft-ietf-teas-yang-te-topo-12.txt, the fully expanded
> > tree diagram (36 pages) is simply in no good relation with the size of
> > the definitions (47 pages). And the authors of this document do the
> > right thing, they provide overview diagrams that leave out lots of
> > details and that are comprehensible. So is it valuable to keep the
> > full dump in the document?
> I personally don't think so, and questioned its usefulness.  I also
> suggested moving to an appendix if they really wanted to keep it.  For
> whatever reason they decided they wanted to keep it which is, of course,
> within their purview.
> 
> So, I think the question for us is: what, beyond the change you suggest
> above, add to the tree draft to cover cases where authors really want to
> include such long trees?

At the end, WGs decide with the input from the authors, reviewers
etc. and not everything needs to have rules that we cast into RFCs.
Perhaps we are better off having a few questions and answers on the
FAQ concerning tree diagrams.

/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/>