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

Juergen Schoenwaelder <j.schoenwaelder@jacobs-university.de> Fri, 03 March 2017 19:13 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 806D91295AF for <netmod@ietfa.amsl.com>; Fri, 3 Mar 2017 11:13:46 -0800 (PST)
X-Virus-Scanned: amavisd-new at amsl.com
X-Spam-Flag: NO
X-Spam-Score: -4.2
X-Spam-Level:
X-Spam-Status: No, score=-4.2 tagged_above=-999 required=5 tests=[BAYES_00=-1.9, RCVD_IN_DNSWL_MED=-2.3, RP_MATCHES_RCVD=-0.001, 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 suOhN_obgzLx for <netmod@ietfa.amsl.com>; Fri, 3 Mar 2017 11:13:45 -0800 (PST)
Received: from atlas3.jacobs-university.de (atlas3.jacobs-university.de [212.201.44.18]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by ietfa.amsl.com (Postfix) with ESMTPS id 3C4301204D9 for <netmod@ietf.org>; Fri, 3 Mar 2017 11:13:45 -0800 (PST)
Received: from localhost (demetrius5.irc-it.jacobs-university.de [10.70.0.222]) by atlas3.jacobs-university.de (Postfix) with ESMTP id 1335572C for <netmod@ietf.org>; Fri, 3 Mar 2017 20:13:44 +0100 (CET)
X-Virus-Scanned: amavisd-new at jacobs-university.de
Received: from atlas3.jacobs-university.de ([10.70.0.205]) by localhost (demetrius5.jacobs-university.de [10.70.0.222]) (amavisd-new, port 10030) with ESMTP id 0zz5eZC_xSnD for <netmod@ietf.org>; Fri, 3 Mar 2017 20:13:41 +0100 (CET)
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 atlas3.jacobs-university.de (Postfix) with ESMTPS for <netmod@ietf.org>; Fri, 3 Mar 2017 20:13:43 +0100 (CET)
Received: from localhost (demetrius4.jacobs-university.de [212.201.44.49]) by hermes.jacobs-university.de (Postfix) with ESMTP id C041320033 for <netmod@ietf.org>; Fri, 3 Mar 2017 20:13:43 +0100 (CET)
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 WUwgqXCa0NGi; Fri, 3 Mar 2017 20:13:42 +0100 (CET)
Received: from elstar.local (elstar.jacobs.jacobs-university.de [10.50.231.133]) by hermes.jacobs-university.de (Postfix) with ESMTP id E114920031; Fri, 3 Mar 2017 20:13:42 +0100 (CET)
Received: by elstar.local (Postfix, from userid 501) id 7F2E33E944CA; Fri, 3 Mar 2017 20:13:48 +0100 (CET)
Date: Fri, 03 Mar 2017 20:13:48 +0100
From: Juergen Schoenwaelder <j.schoenwaelder@jacobs-university.de>
To: netmod@ietf.org
Message-ID: <20170303191348.GA3570@elstar.local>
Mail-Followup-To: netmod@ietf.org
MIME-Version: 1.0
Content-Type: text/plain; charset="us-ascii"
Content-Disposition: inline
User-Agent: Mutt/1.6.0 (2016-04-01)
Archived-At: <https://mailarchive.ietf.org/arch/msg/netmod/KJioNvOr_AIt6ByjPTT1X5361Pk>
Subject: [netmod] rfc 6087bis - stress importance of instance examples
X-BeenThere: netmod@ietf.org
X-Mailman-Version: 2.1.17
Precedence: list
Reply-To: Juergen Schoenwaelder <j.schoenwaelder@jacobs-university.de>
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 19:13:46 -0000

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