Subject: [netmod] tree diagram guidelines

From: Martin Bjorklund <[email-masked]>
Date: Wed, 15 Nov 2017 10:14:54 +0100 (CET)

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

---

From: Robert Wilton <[email-masked]>
Date: Wed, 15 Nov 2017 11:53:24 +0100

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:
> _______________________________________________
> netmod mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/netmod
> .
>

---

From: "Mehmet Ersue" <[email-masked]>
Date: Wed, 15 Nov 2017 23:27:49 +0800

Hi All,

I think having the tree-related guidelines in the tree draft and finalizing 6087bis as planned is useful.
That said a NETMOD wiki explaining the available guidelines with pointers can be used as a starting point and would be additionally helpful.

Mehmet

> -----Original Message-----
> From: netmod [mailto:[email-masked]] On Behalf Of Robert
> Wilton
> Sent: Wednesday, November 15, 2017 6:53 PM
> To: Martin Bjorklund <[email-masked]>; [email-masked]
> Subject: Re: [netmod] tree diagram guidelines
> 
> 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
> 
>

---

From: Mahesh Jethanandani <[email-masked]>
Date: Thu, 16 Nov 2017 07:39:23 +0800

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 <[email-masked]> wrote:
> 
> 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
> 
> 

Mahesh Jethanandani
[email-masked]

---

From: "Mehmet Ersue" <[email-masked]>
Date: Thu, 16 Nov 2017 11:04:17 +0800

The Wiki is useful as a starting point providing a collection of pointers to guideline RFCs and the bis-revisions in development.

Cheers,
Mehmet

> From: netmod [mailto:[email-masked]] On Behalf Of Mahesh
> Jethanandani
> Sent: Thursday, November 16, 2017 7:39 AM
> To: Robert Wilton <[email-masked]>
> Cc: [email-masked]
> 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.
> 
> >> 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
> >>

---

From: Lou Berger <[email-masked]>
Date: Fri, 17 Nov 2017 07:42:33 +0800

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)

---

From: "Mehmet Ersue" <[email-masked]>
Date: Fri, 17 Nov 2017 08:53:38 +0800

Sounds perfect to me.

Mehmet

> From: Lou Berger [mailto:[email-masked]]
> Sent: Friday, November 17, 2017 7:43 AM
> To: Mehmet Ersue <[email-masked]>; 'Mahesh Jethanandani'
> <[email-masked]>; 'Robert Wilton' <[email-masked]>
> Cc: [email-masked]
> (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"
> > The Wiki is useful as a starting point providing a collection of pointers to
> guideline RFCs and the bis-revisions in development.
> >
> > Cheers,
> > Mehmet
> >
> >> 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.
> >>
> >> using the latest draft guidelines, or should then use the published
> >> RFC until 6087bis is actually republshed?
> >>>
> >>> Thanks,
> >>> Rob
> >>>
> >>>
> >>>> 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?
> >>>>
> >>>> this document it is not a big problem that guidelines are spread
> >>>> out over several documents that are difficult to find.
> >>>>
> >>>>
> >>>>
> >>>> /martin
> >>>>

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Fri, 17 Nov 2017 08:00:43 +0100

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.

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