Re: [netmod] tree diagram guidelines

Juergen Schoenwaelder <j.schoenwaelder@jacobs-university.de> Fri, 08 December 2017 07:25 UTC

Return-Path: <j.schoenwaelder@jacobs-university.de>
X-Original-To: netmod@ietfa.amsl.com
Delivered-To: netmod@ietfa.amsl.com
Received: from localhost (localhost [127.0.0.1]) by ietfa.amsl.com (Postfix) with ESMTP id 0DB13129510 for <netmod@ietfa.amsl.com>; Thu, 7 Dec 2017 23:25:37 -0800 (PST)
X-Virus-Scanned: amavisd-new at amsl.com
X-Spam-Flag: NO
X-Spam-Score: -1.9
X-Spam-Level:
X-Spam-Status: No, score=-1.9 tagged_above=-999 required=5 tests=[BAYES_00=-1.9, RCVD_IN_DNSWL_NONE=-0.0001] autolearn=ham autolearn_force=no
Received: from mail.ietf.org ([4.31.198.44]) by localhost (ietfa.amsl.com [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id 21mGY5rnjZBH for <netmod@ietfa.amsl.com>; Thu, 7 Dec 2017 23:25:34 -0800 (PST)
Received: from atlas5.jacobs-university.de (atlas5.jacobs-university.de [212.201.44.20]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by ietfa.amsl.com (Postfix) with ESMTPS id 41CDA120727 for <netmod@ietf.org>; Thu, 7 Dec 2017 23:25:34 -0800 (PST)
Received: from localhost (demetrius5.irc-it.jacobs-university.de [10.70.0.222]) by atlas5.jacobs-university.de (Postfix) with ESMTP id 0A43160; Fri, 8 Dec 2017 08:25:33 +0100 (CET)
X-Virus-Scanned: amavisd-new at jacobs-university.de
Received: from atlas5.jacobs-university.de ([10.70.0.217]) by localhost (demetrius5.jacobs-university.de [10.70.0.222]) (amavisd-new, port 10032) with ESMTP id TTHuQWoRoNev; Fri, 8 Dec 2017 08:25:31 +0100 (CET)
Received: from hermes.jacobs-university.de (hermes.jacobs-university.de [212.201.44.23]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (Client CN "hermes.jacobs-university.de", Issuer "Jacobs University CA - G01" (verified OK)) by atlas5.jacobs-university.de (Postfix) with ESMTPS; Fri, 8 Dec 2017 08:25:32 +0100 (CET)
Received: from localhost (demetrius1.jacobs-university.de [212.201.44.46]) by hermes.jacobs-university.de (Postfix) with ESMTP id C0A1E20129; Fri, 8 Dec 2017 08:25:32 +0100 (CET)
X-Virus-Scanned: amavisd-new at jacobs-university.de
Received: from hermes.jacobs-university.de ([212.201.44.23]) by localhost (demetrius1.jacobs-university.de [212.201.44.32]) (amavisd-new, port 10024) with ESMTP id V0OWwN_CNs5T; Fri, 8 Dec 2017 08:25:31 +0100 (CET)
Received: from elstar.local (elstar.jacobs.jacobs-university.de [10.50.231.133]) by hermes.jacobs-university.de (Postfix) with ESMTP id 1EB912012C; Fri, 8 Dec 2017 08:25:31 +0100 (CET)
Received: by elstar.local (Postfix, from userid 501) id C6A3F41901E3; Fri, 8 Dec 2017 08:24:00 +0100 (CET)
Date: Fri, 08 Dec 2017 08:24:00 +0100
From: Juergen Schoenwaelder <j.schoenwaelder@jacobs-university.de>
To: "Joel M. Halpern" <jmh@joelhalpern.com>
Cc: netmod@ietf.org
Message-ID: <20171208072400.ieuybzrm3kudfsya@elstar.local>
Reply-To: Juergen Schoenwaelder <j.schoenwaelder@jacobs-university.de>
Mail-Followup-To: "Joel M. Halpern" <jmh@joelhalpern.com>, netmod@ietf.org
References: <20171115.101454.1576716701146734257.mbj@tail-f.com> <bb0f2cf8-ca46-21af-02cd-79970a08db7e@cisco.com> <0696749C-0E80-40CC-9905-BD8187CB6D78@gmail.com> <014a01d35e87$98797950$c96c6bf0$@gmail.com> <00143927-dc4d-5db8-e3ce-dbd56366a06c@labn.net> <20171117070043.pm7rn25yj3hxum3q@elstar.local> <4df13805-f4c8-89da-f986-64da816bea0b@labn.net> <1cb63d28-4333-c36a-dbe7-6cc58eaa5a3a@joelhalpern.com>
MIME-Version: 1.0
Content-Type: text/plain; charset="utf-8"
Content-Disposition: inline
X-Clacks-Overhead: GNU Terry Pratchett
Content-Transfer-Encoding: 8bit
In-Reply-To: <1cb63d28-4333-c36a-dbe7-6cc58eaa5a3a@joelhalpern.com>
User-Agent: NeoMutt/20170714 (1.8.3)
Archived-At: <https://mailarchive.ietf.org/arch/msg/netmod/zkIXfGejxXM8nr0-gGfTziH3F5M>
Subject: Re: [netmod] tree diagram guidelines
X-BeenThere: netmod@ietf.org
X-Mailman-Version: 2.1.22
Precedence: list
List-Id: NETMOD WG list <netmod.ietf.org>
List-Unsubscribe: <https://www.ietf.org/mailman/options/netmod>, <mailto:netmod-request@ietf.org?subject=unsubscribe>
List-Archive: <https://mailarchive.ietf.org/arch/browse/netmod/>
List-Post: <mailto:netmod@ietf.org>
List-Help: <mailto:netmod-request@ietf.org?subject=help>
List-Subscribe: <https://www.ietf.org/mailman/listinfo/netmod>, <mailto:netmod-request@ietf.org?subject=subscribe>
X-List-Received-Date: Fri, 08 Dec 2017 07:25:37 -0000

I agree. Fragile pointers to pages that can change anytime are
problematic in static documents.

/js

On Thu, Dec 07, 2017 at 08:04:52PM -0500, Joel M. Halpern wrote:
>     I have been watching this discussion of referencing the wiki page from
> the RFC-to-be about tree diagrams.  I must admit that I am confused as to
> why we would want to do so.
> 
>     For anyone writing a document with a YANG tree, what they are required
> to do is what is in this RFC.  While the wiki page may be interesting, it is
> not normative.
>     For anyone reading an RFC that uses a Tree diagram (a significantly
> larger number of people), what they need to know is in the RFC.  Reading the
> wiki not only is not normative, it may well have content that was not even
> present when the RFC that they are reading was written.  In fact, the
> content of the wiki may contradict what is in the RFC they are reading,
> without indicating any errors having been made.  Which I fear may be
> confusing to the reader.
> 
>     I understand and support wanting to make it easy for readers to find the
> wiki of ongoing discussions of YANG tree diagrams (and other issues.)  But
> it seems like this is the wrong way to achieve the goal.
> 
> Yours,
> Joel
> 
> On 12/7/17 6:38 PM, Lou Berger 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:netmod-bounces@ietf.org] On Behalf Of Mahesh
> > > > > > Jethanandani
> > > > > > Sent: Thursday, November 16, 2017 7:39 AM
> > > > > > To: Robert Wilton <rwilton@cisco.com>
> > > > > > Cc: netmod@ietf.org
> > > > > > 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 <rwilton@cisco.com> 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
> > > > > > > > netmod@ietf.org
> > > > > > > > https://www.ietf.org/mailman/listinfo/netmod
> > > > > > > > .
> > > > > > > > 
> > > > > > > _______________________________________________
> > > > > > > netmod mailing list
> > > > > > > netmod@ietf.org
> > > > > > > https://www.ietf.org/mailman/listinfo/netmod
> > > > > > Mahesh Jethanandani
> > > > > > mjethanandani@gmail.com
> > > > > > 
> > > > > > _______________________________________________
> > > > > > 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
> > 
> > _______________________________________________
> > 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

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