Re: [netmod] rfc 6087bis

Juergen Schoenwaelder <j.schoenwaelder@jacobs-university.de> wrote:
> 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.

+1  And also encourage authors to validate the examples using their
favorite YANG instance validation tool.


/martin

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

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