[netmod] Re: WGLC on draft-ietf-netmod-rfc8407bis

[[e-mail]]

Hi Andy, 

RFC8340 leaves it to the authors to include it or not. It uses statements such as "When long diagrams are included in a document, .."

An outcome of the discussion is that we can't impose one option here. For example, the current situation is that we do already have RFCs (RFC7407, RFC9182, RFC9291, etc.) that do not include the full trees because these are too long, the narrative text is good enough, the document itself is +150 pages, etc. Also, including pages and pages of text that exceeds the max line is not convenient for readers.

The new guidelines include a provision for when the full tree is not included for better consistency among published documents.

Cheers,
Med

> -----Message d'origine-----
> De : Andy Bierman <[e-mail]>
> Envoyé : lundi 14 octobre 2024 18:24
> À : BOUCADAIR Mohamed INNOV/NET <[e-mail]>
> Cc : Mahesh Jethanandani <[e-mail]>; Lou Berger
> <[e-mail]>; [e-mail]; draft-ietf-netmod-
> [e-mail]; Jan Lindblad <[e-mail]>; Kent
> Watsen <[e-mail]>
> Objet : Re: [netmod] WGLC on draft-ietf-netmod-rfc8407bis
> 
> 
> Hi,
> 
> IMO we do not need new procedures to save the reader from a few
> extra pages of YANG tree diagram text.
> 
> This is the only option that makes sense to me:
> 
>    *  Include the full tree in an appendix.
> 
> Andy
> 
> On Sun, Oct 13, 2024 at 10:19 PM <[e-mail]>
> wrote:
> 
> > Hi Mahesh,
> >
> >
> >
> > Yes, this refers to the main body per the structure in
> rfc7322#section-4.
> > Updated accordingly.
> >
> >
> >
> > The diff is available using the same link: Diff:
> > draft-ietf-netmod-rfc8407bis.txt - draft-ietf-netmod-
> rfc8407bis.txt
> >
> <https://eur03.safelinks.protection.outlook.com/?url=https%3A%2F%2
> Faut
> > hor-
> tools.ietf.org%2Fapi%2Fiddiff%3Furl_1%3Dhttps%3A%2F%2Fnetmod-wg.gi
> > thub.io%2Frfc8407bis%2Fdraft-ietf-netmod-
> rfc8407bis.txt%26url_2%3Dhttp
> > s%3A%2F%2Fnetmod-wg.github.io%2Frfc8407bis%2Flong-trees%2Fdraft-
> ietf-n
> > etmod-
> rfc8407bis.txt&data=05%7C02%7Cmohamed.boucadair%40orange.com%7C3
> >
> 60a053d61314c7851bc08dcec6c99f5%7C90c7a20af34b40bfbc48b9253b6f5d20
> %7C0
> >
> %7C0%7C638645198411517106%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAw
> MDAi
> >
> LCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C0%7C%7C%7C&sdata=
> PUXU
> > FFa2G1oGYjtnRYtC9hFJkRu5Nx%2FISQob3izoYds%3D&reserved=0>
> >
> >
> >
> > Thanks.
> >
> >
> >
> > Cheers,
> >
> > Med
> >
> >
> >
> > *De :* Mahesh Jethanandani <[e-mail]> *Envoyé :*
> samedi
> > 12 octobre 2024 01:54 *À :* BOUCADAIR Mohamed INNOV/NET
> > <[e-mail]> *Cc :* Lou Berger
> <[e-mail]>;
> > [e-mail]; [e-mail]; Jan
> Lindblad
> > <[e-mail]>; Kent Watsen <[e-mail]> *Objet
> :* Re:
> > [netmod] WGLC on draft-ietf-netmod-rfc8407bis
> >
> >
> >
> >
> > Hi Med,
> >
> >
> >
> > Speaking as a contributor ...
> >
> >
> >
> > On Oct 11, 2024, at 8:47 AM, [e-mail] wrote:
> >
> >
> >
> > Hi Lou, Kent, all,
> >
> >
> >
> > Taking into account the feedback received so far, I suggest the
> > following
> > change:
> >
> >
> >
> > OLD:
> >
> >    YANG tree diagrams provide a concise representation of a YANG
> > module
> >
> >    and SHOULD be included to help readers understand YANG module
> >
> >    structure.  If the complete tree diagram for a module becomes
> long
> >
> >    (more than 2 pages, typically), the diagram SHOULD be split
> into
> >
> >    several smaller diagrams (a.k.a subtrees).  For the reader's
> >
> >    convenience, a subtree should fit within a page.  If the
> complete
> >
> >    tree diagram is too long (more than 5 pages, typically) even
> with
> >
> >    groupings unexpanded (Section 2.2 of [RFC8340]), the authors
> SHOULD
> >
> >    NOT include it in the document.  A stable pointer to retrieve
> the
> >
> >    full tree MAY be included.
> >
> >
> >
> > NEW:
> >
> >    YANG tree diagrams provide a concise representation of a YANG
> > module
> >
> >    and SHOULD be included to help readers understand YANG module
> >
> >    structure.  If the complete tree diagram for a module becomes
> long
> >
> >    (more than 2 pages, typically), the diagram SHOULD be split
> into
> >
> >    several smaller diagrams (a.k.a subtrees).  For the reader's
> >
> >    convenience, a subtree should fit within a page.  If the
> complete
> >
> >    tree diagram is too long (more than 5 pages, typically) even
> with
> >
> >    groupings unexpanded (Section 2.2 of [RFC8340]), the authors
> SHOULD
> >
> >    NOT include it in the main document.  Instead, authors MAY
> consider
> >
> >    the following options:
> >
> >
> >
> > [mj] Not clear what you mean by “main document”. Do you mean the
> > normative section of the document? If so, please edit it to say
> that.
> >
> >
> >
> > Thanks
> >
> >
> >
> >
> >
> >    *  Provide only a stable pointer to retrieve the full tree.
> The
> > full
> >
> >       tree is thus not provided at all.
> >
> >
> >
> >    *  Include a note about how to generate the full tree.
> >
> >
> >
> >    *  A combination of the first and second bullets.
> >
> >
> >
> >    *  Include the full tree in an appendix.
> >
> >
> >
> > For convenience:
> >
> >    - Diff: Diff: draft-ietf-netmod-rfc8407bis.txt -
> >    draft-ietf-netmod-rfc8407bis.txt
> >
> <https://eur03.safelinks.protection.outlook.com/?url=https%3A%2F%2
> Fauthor-
> tools.ietf.org%2Fapi%2Fiddiff%3Furl_1%3Dhttps%3A%2F%2Fnetmod-
> wg.github.io%2Frfc8407bis%2Fdraft-ietf-netmod-
> rfc8407bis.txt%26url_2%3Dhttps%3A%2F%2Fnetmod-
> wg.github.io%2Frfc8407bis%2Flong-trees%2Fdraft-ietf-netmod-
> rfc8407bis.txt&data=05%7C02%7Cmohamed.boucadair%40orange.com%7C360
> a053d61314c7851bc08dcec6c99f5%7C90c7a20af34b40bfbc48b9253b6f5d20%7
> C0%7C0%7C638645198411540339%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLj
> AwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C0%7C%7C%7C&
> sdata=68CtKMDgxzWjl4IsKqxJlSLpvOHAflb0Cv5TQFwExN0%3D&reserved=0>
> >    - PR:
> >
> https://eur03.safelinks.protection.outlook.com/?url=https%3A%2F%2F
> gith
> > ub.com%2Fnetmod-
> wg%2Frfc8407bis%2Fpull%2F70%2Ffiles&data=05%7C02%7Cmoh
> >
> amed.boucadair%40orange.com%7C360a053d61314c7851bc08dcec6c99f5%7C9
> 0c7a
> >
> 20af34b40bfbc48b9253b6f5d20%7C0%7C0%7C638645198411557810%7CUnknown
> %7CT
> >
> WFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJ
> XVCI
> >
> 6Mn0%3D%7C0%7C%7C%7C&sdata=%2BkYIcnZV7Wwi4tUS6uOObRMUMcdt4xxyiNBOW
> QXGp
> > wE%3D&reserved=0
> >
> >
> >
> > Better?
> >
> >
> >
> > Cheers,
> >
> > Med
> >
> >
> >
> > *De :* BOUCADAIR Mohamed INNOV/NET
> > *Envoyé :* mercredi 2 octobre 2024 11:13 *À :* 'Lou Berger'
> > <[e-mail]>; [e-mail];
> > [e-mail]; Jan Lindblad (jlindbla) <
> > [e-mail]> *Cc :* Kent Watsen <[e-mail]>
> *Objet
> > :* RE: [netmod] Re: WGLC on draft-ietf-netmod-rfc8407bis
> >
> >
> >
> > Hi Lou,
> >
> >
> >
> >    - Keeping long trees in the main document is really not
> helpful to
> >    digest a module. I also know by experience that this raises
> comments,
> >    including from the IESG.
> >    - Keeping long trees that exceed 69 line max in the main or
> as an
> >    appendix is really hard to follow.
> >    - There are already RFCs out there do not include long trees,
> but a
> >    note about how to generate it. The narrative text uses small
> snippets to
> >    help readers walk through the model.
> >    - Some consistency is needed in how we document our modules +
> help
> >    authors with clear guidance (e.g., characterize what is a
> long
> > tree)
> >
> >
> >
> > I’m afraid that we can’t simply leave the OLD 8407 as it is.
> >
> >
> >
> > That’s said, I’m only the pen holder and will implement whatever
> the
> > WG decides here.
> >
> >
> >
> > Cheers,
> >
> > Med
> >
> >
> >
> > *De :* Lou Berger <[e-mail]>
> > *Envoyé :* mardi 1 octobre 2024 13:37
> > *À :* BOUCADAIR Mohamed INNOV/NET
> <[e-mail]>;
> > [e-mail]; [e-mail]; Jan
> Lindblad
> > (jlindbla) <[e-mail]>
> > *Cc :* Kent Watsen <[e-mail]> *Objet :* Re: [netmod]
> Re:
> > WGLC on draft-ietf-netmod-rfc8407bis
> >
> >
> >
> > Med, Jan, WG,
> >
> > I have to say that I read the discussion concluding with to NOT
> change
> > the current recommendation, see
> >
> https://eur03.safelinks.protection.outlook.com/?url=https%3A%2F%2F
> mail
> > archive.ietf.org%2Farch%2Fmsg%2Fnetmod%2F0Q0YiyNi15V-Szzf5awLVh-
> 15_c%2
> >
> F&data=05%7C02%7Cmohamed.boucadair%40orange.com%7C360a053d61314c78
> 51bc
> >
> 08dcec6c99f5%7C90c7a20af34b40bfbc48b9253b6f5d20%7C0%7C0%7C63864519
> 8411
> >
> 573595%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzI
> iLCJ
> >
> BTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C0%7C%7C%7C&sdata=FuJbQGSOk7%2FkMXATR
> 1fn3
> > YScP4MBfkRWYvYXz90NyNI%3D&reserved=0
> >
> > I personally use an ereader (or computer) more than paper and
> having
> > to go to a static URL -- probably when I'm off line -- does NOT
> seem
> > like something we should be recommending.  Furthermore, I'm not
> sure
> > what our process has to say about having the HTML include *text
> > content* that is not in the text version.
> >
> > Again just my perspective.
> >
> > What do others think? do they feel strongly that this change
> from the
> > current recommendation (in RFC8340) of having long trees in
> appendixes
> > is a good or bad idea? (Yes, I'm in the strongly against camp.)
> >
> > Thanks,
> >
> > Lou
> >
> > On 10/1/2024 4:24 AM, [e-mail] wrote:
> >
> > Hi Lou,
> >
> >
> >
> >    1. The comment that triggered the change and companion thread
> where
> >    this was discussed and changes proposed can be seen at:
> >
> >
> https://eur03.safelinks.protection.outlook.com/?url=https%3A%2F%2F
> mail
> > archive.ietf.org%2Farch%2Fmsg%2Fnetmod%2F-
> b2HX0XUK49qJB19LHu6MC0D9zc%2F&data=05%7C02%7Cmohamed.boucadair%40o
> range.com%7C360a053d61314c7851bc08dcec6c99f5%7C90c7a20af34b40bfbc4
> 8b9253b6f5d20%7C0%7C0%7C638645198411584985%7CUnknown%7CTWFpbGZsb3d
> 8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3
> D%7C0%7C%7C%7C&sdata=r4xdN4asqklRHaI%2BIixWX29CCw7i1QBlmAHlNXrKjng
> %3D&reserved=0
____________________________________________________________________________________________________________
Ce message et ses pieces jointes peuvent contenir des informations confidentielles ou privilegiees et ne doivent donc
pas etre diffuses, exploites ou copies sans autorisation. Si vous avez recu ce message par erreur, veuillez le signaler
a l'expediteur et le detruire ainsi que les pieces jointes. Les messages electroniques etant susceptibles d'alteration,
Orange decline toute responsabilite si ce message a ete altere, deforme ou falsifie. Merci.

This message and its attachments may contain confidential or privileged information that may be protected by law;
they should not be distributed, used or copied without authorisation.
If you have received this email in error, please notify the sender and delete this message and its attachments.
As emails may be altered, Orange is not liable for messages that have been modified, changed or falsified.
Thank you.