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

[Ladislav Lhotka]

> On 8 Mar 2017, at 18:40, Kent Watsen  wrote:
> 
> 
> 
>>> 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.
> 
> 
> Please note this from the latest 6087bis update:
> 
>   4.12.  Module Usage Examples
> 
>   Each specification that defines one or more modules SHOULD contain
>   usage examples, either throughout the document or in an appendix.
>   This includes example XML instance document snippets to demonstrate
>   the intended usage of the YANG module(s).
> 
> and I already wrote this:
> 
>  Nice addition, but should it say something about JSON, in addition to XML?

I'd suggest:

"This includes example instance documents or snippets in an appropriate 
encoding to demonstrate the intended usage of the YANG module(s)."

Lada

>  Perhaps that, unless there is a reason to only pick one encoding, examples
>  should be split between the two?  - just throwing it out there to see if 
> this is
>  something we might want to recommend...thoughts?
> 
>  https://mailarchive.ietf.org/arch/msg/netmod/dOpSYzM_J05Sdmgt-MyYmqJIUz0
> 
> 
> K.
> 
> 
> ___
> netmod mailing list
> netmod@ietf.org
> https://www.ietf.org/mailman/listinfo/netmod

--
Ladislav Lhotka, CZ.NIC Labs
PGP Key ID: 0xB8F92B08A9F76C67





___
netmod mailing list
netmod@ietf.org
https://www.ietf.org/mailman/listinfo/netmod

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

[Juergen Schoenwaelder]

On Wed, Mar 08, 2017 at 05:40:44PM +, Kent Watsen wrote:
> 
> 
> >> 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.
> 
> 
> Please note this from the latest 6087bis update:
> 
>4.12.  Module Usage Examples
> 
>Each specification that defines one or more modules SHOULD contain
>usage examples, either throughout the document or in an appendix.
>This includes example XML instance document snippets to demonstrate
>the intended usage of the YANG module(s).
> 
> and I already wrote this:
> 
>   Nice addition, but should it say something about JSON, in addition to XML?
>   Perhaps that, unless there is a reason to only pick one encoding, examples
>   should be split between the two?  - just throwing it out there to see if 
> this is
>   something we might want to recommend...thoughts?
> 
>   https://mailarchive.ietf.org/arch/msg/netmod/dOpSYzM_J05Sdmgt-MyYmqJIUz0
>

I think the purpose of section 4.12 is to encourage people to check
that their definitions lead to reasonable instance documents. It is
easy to choose identifiers in the schema that look reasonable in the
schema but horrible in instance documents. The purpose of the examples
should in general not be to showcase that YANG can have different
instance representation formats. I would leave it to the WG to decide
whether they prefer examples in JSON or XML. In LMAP, I once had
examples in both XML and JSON and that was not useful (lots of
additional pages with no real added value).

All that said, you likely end up naming things slightly different
depending on whether you look primarily at a JSON encoded instance
document or an XML encoded instance document. But I do not care much
as long as identifiers are reasonably consistent.

/js

-- 
Juergen Schoenwaelder   Jacobs University Bremen gGmbH
Phone: +49 421 200 3587 Campus Ring 1 | 28759 Bremen | Germany
Fax:   +49 421 200 3103 

___
netmod mailing list
netmod@ietf.org
https://www.ietf.org/mailman/listinfo/netmod

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

[Kent Watsen]

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


Please note this from the latest 6087bis update:

   4.12.  Module Usage Examples

   Each specification that defines one or more modules SHOULD contain
   usage examples, either throughout the document or in an appendix.
   This includes example XML instance document snippets to demonstrate
   the intended usage of the YANG module(s).

and I already wrote this:

  Nice addition, but should it say something about JSON, in addition to XML?
  Perhaps that, unless there is a reason to only pick one encoding, examples
  should be split between the two?  - just throwing it out there to see if this 
is
  something we might want to recommend...thoughts?

  https://mailarchive.ietf.org/arch/msg/netmod/dOpSYzM_J05Sdmgt-MyYmqJIUz0


K.


___
netmod mailing list
netmod@ietf.org
https://www.ietf.org/mailman/listinfo/netmod

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

[Martin Bjorklund]

Juergen Schoenwaelder  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 
> 
> ___
> 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

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

[Joel M. Halpern]

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 

___
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



___
netmod mailing list
netmod@ietf.org
https://www.ietf.org/mailman/listinfo/netmod

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

[Phil Shafer]

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

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

[Juergen Schoenwaelder]

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 

___
netmod mailing list
netmod@ietf.org
https://www.ietf.org/mailman/listinfo/netmod