Re: [netmod] tree diagram guidelines

[Andy Bierman <[e-mail]>]

Hi,

These changes are OK with me.



Andy


On Thu, Dec 7, 2017 at 3:38 PM, Lou Berger <[e-mail]> wrote:

> Hi,
>
> Following up on this discussion (and hoping to wrap it up):
>
> I have created two  wikis off of
> https://trac.ietf.org/trac/netmod/wiki/WikiStart, one for 6087bis
> content and the other for section 3 of tree diagrams.  I also propose
> the following changes to the tree-diagrams draft:
>
> To section 3 intro, add:
>     For the most current quidelines being developed, please see the IETF
> NetMod Working
>    Group Wiki, see:  https://trac.ietf.org/trac/netmod/wiki/WikiStart
>
> Add :
>   3.2.  Groupings
>
>    If the YANG module is comprised of groupings only, then the tree
>    diagram should contain the groupings.  The 'pyang' compiler can be
>    used to produce a tree diagram with groupings using the "-f tree --
>    tree-print-groupings" command line parameters.
>
> And to section 3.3, start with:
>
>    Tree diagrams can be split into sections to correspond to document
>    structure.
>
> For 6087 bis, I think section 3.4 gets replaced with something like.
>
>     YANG tree diagrams provide a concise representation of a YANG module,
>    and SHOULD be included to help readers understand YANG module
>     structure.  Guidelines on tree diagrams can be found in Section 3 of
>     [I-D.ietf-netmod-yang-tree-diagrams].
>
> These changes can be found at:
> https://github.com/netmod-wg/yang-tree-diagrams/commit/
> 53919e0a4549c285758eb5aaaf02cf980269afff
>
> This leaves the intended status as the key open issue on the draft.
>
> Lou
>
>
> On 11/17/2017 2:00 AM, Juergen Schoenwaelder wrote:
> > I am confused. I think there was some consensus to
> >
> > - include all tree related guidelines in the tree document, remove all
> tree
> >   related guidelines from 6087bis and have 6087bis point to the tree
> document
> >   (which it already does)
> >
> > The rest is pointless since AFAIK there is no wiki guidelines pages to
> > point to and there is AFAIK nobody in place to actually maintain such
> > a wiki page. Perhaps a wiki is the future but until future has
> > arrived, we should not point to it.
> >
> > The other proposal I heard was to have a landing page that points to
> > the current guideline work which points to the relevant documents. A
> > wiki pointing to RFCs and ID, not RFC pointing to wikis. So this does not
> > affect the documents.
> >
> > /js
> >
> > PS: I am happy to add pointers to guidelines as a section to the
> >     wikipedia page.
> >
> > On Fri, Nov 17, 2017 at 07:42:33AM +0800, Lou Berger wrote:
> >> To circle back to this.  My sense of this discussion (as contributor) is
> >> (a) the tree diagrams draft should be updated to point to a "guidelines"
> >> wiki page for "the most current guidelines"
> >> (b) the tree diagrams draft should be updated to include a full set of
> the
> >> current tree related guidelines
> >> (c) 6087bis should be updated to point to a "guidelines" wiki page for
> "the
> >> most current guidelines"
> >> (d) 6087bis should have it's tree guidelines point to the tree diagrams
> >> document -- in addition to pointing to the wiki
> >>
> >> Does this sound right?
> >>
> >> Lou
> >> (as tree co-author)
> >>
> >> On 11/16/2017 11:04 AM, Mehmet Ersue wrote:
> >>> The Wiki is useful as a starting point providing a collection of
> pointers to guideline RFCs and the bis-revisions in development.
> >>>
> >>> Cheers,
> >>> Mehmet
> >>>
> >>>> -----Original Message-----
> >>>> From: netmod [mailto:[e-mail]] On Behalf Of Mahesh
> >>>> Jethanandani
> >>>> Sent: Thursday, November 16, 2017 7:39 AM
> >>>> To: Robert Wilton <[e-mail]>
> >>>> Cc: [e-mail]
> >>>> Subject: Re: [netmod] tree diagram guidelines
> >>>>
> >>>> Other SDOs can and follow the work in IETF through the RFCs we
> publish.
> >>>> They do not follow wiki’s, unless the document itself says, “here are
> the
> >>>> guidelines, but if you are looking for the latest, go to this wiki”.
> I therefore
> >>>> would support the proposal outlined below. It gives the SDO a stable
> point of
> >>>> reference with a document, which gets updated occasionally, but also
> allows
> >>>> them to peak at what is coming down the pipeline.
> >>>>
> >>>> Thanks.
> >>>>
> >>>>> On Nov 15, 2017, at 6:53 PM, Robert Wilton <[e-mail]>
> wrote:
> >>>>>
> >>>>> I liked the suggestion from Chris Hopps:
> >>>>>
> >>>>> I think that it was along the lines of ...
> >>>>>
> >>>>> The RFC contains a reference at the top that states that updates to
> the
> >>>> guidelines is available on a wiki at ....
> >>>>> Every few years the guidelines on the wiki can be folded into a
> latest
> >>>> version of the guidelines draft.
> >>>>> 6087bis looks to be 3.5 years old.  Should folks, e.g. at BBF,,
> IEEE, or MEF be
> >>>> using the latest draft guidelines, or should then use the published
> RFC until
> >>>> 6087bis is actually republshed?
> >>>>> Thanks,
> >>>>> Rob
> >>>>>
> >>>>>
> >>>>> On 15/11/2017 10:14, Martin Bjorklund wrote:
> >>>>>> Hi,
> >>>>>>
> >>>>>> There was a proposal in the meeting today to have the guidelines for
> >>>>>> tree diagrams in a wiki, instead of having them in 6087bis or in the
> >>>>>> tree diagram document.
> >>>>>>
> >>>>>> Was the proposal really to have a wiki for just the tree guidelines,
> >>>>>> or was the proposal to withdraw 6087bis from the process and instead
> >>>>>> publish all guidelines as a wiki?
> >>>>>>
> >>>>>> If it is the former, is it really worth it?
> >>>>>>
> >>>>>> Advantages with a wiki:
> >>>>>>
> >>>>>>    +  It can be updated more easily
> >>>>>>
> >>>>>> Some drawbacks:
> >>>>>>
> >>>>>>    -  It can be updated more easily
> >>>>>>       (meaning they are less stable)
> >>>>>>
> >>>>>>    -  Wikis tend to not be alive after some time, and are not that
> >>>>>>       easy to find.  Just try to find the various YANG-related wikis
> >>>>>>       we've tried to maintain over the years.
> >>>>>>
> >>>>>>    -  Links in RFCs also have problems.  Sites are re-orginized etc.
> >>>>>>       As an example, the link to the security guidelines template in
> >>>>>>       RFC 6087 doesn't work anymore.
> >>>>>>
> >>>>>>    -  People that are looking for a stable reference will have
> problems
> >>>>>>       (I think Rob mentioned that IEEE still refer to RFC 6087
> (which
> >>>>>>       is understandable; that's the published version).
> >>>>>>
> >>>>>>    -  Who maintains the Wiki, and what are the rules for updating
> it?
> >>>>>>
> >>>>>>
> >>>>>> I suggest we have the tree-related guidelines (actually just a few
> >>>>>> sentences) in the tree draft, and since 6087bis already refers to
> >>>>>> this document it is not a big problem that guidelines are spread out
> >>>>>> over several documents that are difficult to find.
> >>>>>>
> >>>>>>
> >>>>>>
> >>>>>> /martin
> >>>>>>
> >>>>>> _______________________________________________
> >>>>>> netmod mailing list
> >>>>>> [e-mail]
> >>>>>> https://www.ietf.org/mailman/listinfo/netmod
> >>>>>> .
> >>>>>>
> >>>>> _______________________________________________
> >>>>> netmod mailing list
> >>>>> [e-mail]
> >>>>> https://www.ietf.org/mailman/listinfo/netmod
> >>>> Mahesh Jethanandani
> >>>> [e-mail]
> >>>>
> >>>> _______________________________________________
> >>>> netmod mailing list
> >>>> [e-mail]
> >>>> https://www.ietf.org/mailman/listinfo/netmod
> >>> _______________________________________________
> >>> netmod mailing list
> >>> [e-mail]
> >>> https://www.ietf.org/mailman/listinfo/netmod
> >>>
> >> _______________________________________________
> >> netmod mailing list
> >> [e-mail]
> >> https://www.ietf.org/mailman/listinfo/netmod
>
>