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/>
- [netmod] tree diagram guidelines Martin Bjorklund
- Re: [netmod] tree diagram guidelines Robert Wilton
- Re: [netmod] tree diagram guidelines Mehmet Ersue
- Re: [netmod] tree diagram guidelines Mahesh Jethanandani
- Re: [netmod] tree diagram guidelines Mehmet Ersue
- Re: [netmod] tree diagram guidelines Lou Berger
- Re: [netmod] tree diagram guidelines Mehmet Ersue
- Re: [netmod] tree diagram guidelines Juergen Schoenwaelder
- Re: [netmod] tree diagram guidelines Lou Berger
- Re: [netmod] tree diagram guidelines Joel M. Halpern
- Re: [netmod] tree diagram guidelines Susan Hares
- Re: [netmod] tree diagram guidelines Juergen Schoenwaelder
- Re: [netmod] tree diagram guidelines Juergen Schoenwaelder
- Re: [netmod] tree diagram guidelines Martin Bjorklund
- Re: [netmod] tree diagram guidelines Andy Bierman