Re: [netmod] tree diagram guidelines

[Lou Berger <[e-mail]>]

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