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

Lou Berger <lberger@labn.net> Fri, 27 October 2017 12:36 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 BE81C13F546 for <netmod@ietfa.amsl.com>; Fri, 27 Oct 2017 05:36:58 -0700 (PDT)
X-Virus-Scanned: amavisd-new at amsl.com
X-Spam-Flag: NO
X-Spam-Score: -4.701
X-Spam-Level:
X-Spam-Status: No, score=-4.701 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] 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 UY4dAsGiNYc7 for <netmod@ietfa.amsl.com>; Fri, 27 Oct 2017 05:36:57 -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 429A913B262 for <netmod@ietf.org>; Fri, 27 Oct 2017 05:36:57 -0700 (PDT)
Received: from cmgw4 (unknown [10.0.90.85]) by gproxy6.mail.unifiedlayer.com (Postfix) with ESMTP id BFD851E07A6 for <netmod@ietf.org>; Fri, 27 Oct 2017 06:36:55 -0600 (MDT)
Received: from box313.bluehost.com ([69.89.31.113]) by cmgw4 with id Sccr1w00w2SSUrH01ccud5; Fri, 27 Oct 2017 06:36:55 -0600
X-Authority-Analysis: v=2.2 cv=JNNLi4Cb 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=32qfTp0iF-ENOMR136MA:9 a=QEXdDO2ut3YA:10
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=PRcftW9CBW/U42131yMjBJvbv7Z7ikpCnWFOQfOa9iY=; b=rIG/UmCmcis9/LnwXU5Icl82ce h2Wp2tfLYOUrcoSoeK5bAbDSfrvAS3H7ioto4VuIsWYrc35PLINqq1V77OLEz8wIoXztUQ6d91FMs KC8TBqkdAtSG4jIX3odIhww9j;
Received: from pool-100-15-86-101.washdc.fios.verizon.net ([100.15.86.101]:50366 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 1e83sZ-000tU8-Qi; Fri, 27 Oct 2017 06:36:51 -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> <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> <20171027115700.u5xwq5xw347jbclp@elstar.local>
From: Lou Berger <lberger@labn.net>
Message-ID: <58770c00-2d4a-f5b2-c0bf-cf52d680577a@labn.net>
Date: Fri, 27 Oct 2017 08:36:43 -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: <20171027115700.u5xwq5xw347jbclp@elstar.local>
Content-Type: text/plain; charset=utf-8
Content-Transfer-Encoding: 8bit
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: 1e83sZ-000tU8-Qi
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]:50366
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/FOjv7UkescIvPxM_cRY3_3EQJVg>
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 12:36:59 -0000

Juergen,


On 10/27/2017 7:57 AM, Juergen Schoenwaelder wrote:
> 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.

Having a guidelines document that evolves naturally over time is just
fine, much like coding conventions.  But trying to bundle or wait for
the convention update both increases the cost of doing guidelines and
leaves a time window when the guidelines are not documented.  While in
some cases this may just fine, I think in this case it would leave much
"folklore" undocumented.  In other words, I think we should capture the
guidelines as best as we can in this document. As I think I've stated
publicly before, I also think the we as WG have to figure out how to
work more "nimbly" by resisting the temptation to have big documents
that cover all aspects of the particular topic at once.

I do think your observation on having two sets of guidelines is correct
and not a good thing.  We can address this quite simply by (a) marking
this document as updating 6087bis and (b) ensuring we have a full
replacement to the tree guidelines provided in that 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.
absolutely agree!

Cheers,
Lou
> Perhaps we are better off having a few questions and answers on the
> FAQ concerning tree diagrams.
>
> /js
>