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

[Phil Shafer <[e-mail]>]

+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: [phone]         Campus Ring 1 | 28759 Bremen | Germany
>Fax:   [phone]         <http://www.jacobs-university.de/>
>
>_______________________________________________
>netmod mailing list
>[e-mail]
>https://www.ietf.org/mailman/listinfo/netmod