Re: [netmod] rfc 6087bis - stress importance of instance examples

"Joel M. Halpern" <jmh@joelhalpern.com> Fri, 03 March 2017 21:08 UTC

Return-Path: <jmh@joelhalpern.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 A4BD412951B for <netmod@ietfa.amsl.com>; Fri, 3 Mar 2017 13:08:32 -0800 (PST)
X-Virus-Scanned: amavisd-new at amsl.com
X-Spam-Flag: NO
X-Spam-Score: -2.701
X-Spam-Level:
X-Spam-Status: No, score=-2.701 tagged_above=-999 required=5 tests=[BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, RCVD_IN_DNSWL_LOW=-0.7, SPF_HELO_PASS=-0.001, SPF_PASS=-0.001, URIBL_BLOCKED=0.001] autolearn=ham autolearn_force=no
Authentication-Results: ietfa.amsl.com (amavisd-new); dkim=pass (1024-bit key) header.d=joelhalpern.com
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 P2xp4aAUYnz9 for <netmod@ietfa.amsl.com>; Fri, 3 Mar 2017 13:08:30 -0800 (PST)
Received: from maila2.tigertech.net (maila2.tigertech.net [208.80.4.152]) (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 993581295DC for <netmod@ietf.org>; Fri, 3 Mar 2017 13:08:30 -0800 (PST)
Received: from localhost (localhost [127.0.0.1]) by maila2.tigertech.net (Postfix) with ESMTP id 510E6240972; Fri, 3 Mar 2017 13:08:30 -0800 (PST)
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=joelhalpern.com; s=1.tigertech; t=1488575310; bh=N8ucojYB/ep0CbBNetqVlGDYlIqHsVDlsEHX8qLpONk=; h=Subject:To:References:Cc:From:Date:In-Reply-To:From; b=jkW64L4ewDSTu2b1x9VlEvWyeEZzo8ivQvdK2lbn/QSeXKhfcgIdSg1T0+QG+tduv 2m20Pfbvnhz2zvce2/FAcvICQiW9iLZOAQ2XqYRJTcEO8zI0BLAnYwtTKawinUEu7A rSfC8r2g/1SoKagd2FWV5xfb6NLdJS4mInMeK/6o=
X-Virus-Scanned: Debian amavisd-new at maila2.tigertech.net
Received: from Joels-MacBook-Pro.local (209-255-163-147.ip.mcleodusa.net [209.255.163.147]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by maila2.tigertech.net (Postfix) with ESMTPSA id C1CDA2408D9; Fri, 3 Mar 2017 13:08:29 -0800 (PST)
To: Phil Shafer <phil@juniper.net>, Juergen Schoenwaelder <j.schoenwaelder@jacobs-university.de>
References: <201703032005.v23K5AAe059307@idle.juniper.net>
From: "Joel M. Halpern" <jmh@joelhalpern.com>
Message-ID: <64e6926d-d884-e3df-cb11-a13714297d8f@joelhalpern.com>
Date: Fri, 3 Mar 2017 16:08:28 -0500
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.12; rv:45.0) Gecko/20100101 Thunderbird/45.7.1
MIME-Version: 1.0
In-Reply-To: <201703032005.v23K5AAe059307@idle.juniper.net>
Content-Type: text/plain; charset=windows-1252; format=flowed
Content-Transfer-Encoding: 7bit
Archived-At: <https://mailarchive.ietf.org/arch/msg/netmod/gO3G1LIOflbsoU3GUpEatQOrka0>
Cc: netmod@ietf.org
Subject: Re: [netmod] rfc 6087bis - stress importance of instance examples
X-BeenThere: netmod@ietf.org
X-Mailman-Version: 2.1.17
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, 03 Mar 2017 21:08:32 -0000

I would have to agree that examples are very useful.

they are useful for comprehensibility even in cases the YANG structure 
may be unwieldly.  For example, if the XML / JSON is expected to be 
generated (as well as consumed) by programmatic processes.

Yours,
Joel

On 3/3/17 3:05 PM, Phil Shafer wrote:
> +1.
>
> As someone who does internal code review for Juniper changes, having
> an example is a huge help to the reviewer (me).  It also helps to
> convince the module author (them) that what they are advocating
> will look horrible.
>
> Thanks,
>  Phil
>
>
>
> Juergen Schoenwaelder writes:
>> Hi,
>>
>> my experience is that when writing YANG modules it is tremendously
>> helpful to focus on the instance documents. I find it essential to
>> write down example snippets of instance documents to see whether they
>> look elegant or clumsy. This is often not easy to determine from just
>> reading a YANG model, in particular if groupings are involved. Examples
>> help so much - you can easily spot whether the usage of singular or
>> plural is reasonable in your names, whether you have redundancy in
>> your names, whether the overall organization is effective. Even better,
>> we have tools that can validate the examples so we can even be sure
>> the examples are correct. (And if you do not know whether you got
>> your pattern statement right, well, one way is to write examples.)
>>
>> I think we should encourage authors to write examples. It will help
>> them to create better models and it will help reviewers tremendously
>> while reviewing models. Good examples will also help users to get
>> started.
>>
>> /js (who apparently is doing some heavy YANG reviewing work today)
>>
>> --
>> 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/>
>>
>> _______________________________________________
>> netmod mailing list
>> netmod@ietf.org
>> https://www.ietf.org/mailman/listinfo/netmod
>
> _______________________________________________
> netmod mailing list
> netmod@ietf.org
> https://www.ietf.org/mailman/listinfo/netmod
>