Re: [netmod] Long trees RE: Next steps for draft-ietf-netmod-rfc8407bis

[Andy Bierman <[e-mail]>]

On Tue, Mar 5, 2024 at 1:47 PM Kent Watsen <[e-mail]> wrote:

> In addition to improving IETF-published artifacts, it would be nice if
> there were a module-browser that acted a little bit like an IDE, jumping to
> where in other modules imported bits are defined.  Perhaps in
> NetconfCentral or YANG Catalog.  This jumping behavior could exist in both
> the text and tree-diagram views.
>
>

I like the plain-text full tree diagram that is usually present before the
YANG module.
Often the groupings and typedefs are from external modules, and/or are
difficult to figure out.
Yet the groupings and typedefs must be found and read to understand the
model.

It would be nice if the HTML version of the draft/RFC had links in the tree
diagram to the actual YANG statements.

DRY vs. WET: the structure of a YANG module (i.e. dividing into sections)
is too complex have strict rules.
A tree diagram for the definitions relevant to each section is usually
helpful, in addition to the full tree diagram.
I would avoid SHOULD and SHOULD NOT for this issue.



> K.
>

Andy


>
>
> On Mar 5, 2024, at 11:21 AM, Italo Busi <Italo.Busi=
> [e-mail]> wrote:
>
> I like the idea of relying on tooling with hyperlinks
>
>
>
> For txt and pdf, I agree that a link is the best option since these
> formats are not optimized for including YANG trees
>
> Italo
>
>
>
> *From:* Kent Watsen <[e-mail]>
> *Sent:* martedì 5 marzo 2024 16:02
> *To:* [e-mail]
> *Cc:* Italo Busi <[e-mail]>; Qin Wu <[e-mail]>;
> Mahesh Jethanandani <[e-mail]>; [e-mail]
> *Subject:* Re: [netmod] Long trees RE: Next steps for
> draft-ietf-netmod-rfc8407bis
>
>
>
>
>
> It seems that there are two camps:
>
>
>
>             1) those that want the tree-diagrams to be as DRY as possible
>
>             2) those that want the tree-diagrams to be as WET as possible
>
>
>
>                           DRY = Don't Repeat Yourself
>
>                           WET = Write Every Time
>
>
>
> Tooling can help both cases.
>
>
>
> For (1), the tree-diagrams are unexpanded, but surrounding text should
> point to where each used-grouping is defined.   The better tooling-assisted
> approach, is for the used groupings *inside the tree-diagram” to become
> hyperlinks (only possible in supporting formats).   Extending this idea
> further, hyperlinks could be provided for typedefs and identities too.
>
>
>
> For (2), for plain-text and PDF formats, a link to where the image can be
> accessed would be nice.  For the HTML format, inlining the complete
> (unfolded) tree-diagram with horizontal-scrolling would be ideal.
>
>
>
> Kent
>
>
>
>
>
> On Mar 5, 2024, at 3:01 AM, [e-mail] wrote:
>
>
>
> Hi Italo,
>
>
>
> Thanks for sharing your thoughts.
>
>
>
> Please see inline.
>
>
>
> Cheers,
>
> Med
>
>
>
> *De :* Italo Busi <[e-mail]>
> *Envoyé :* lundi 4 mars 2024 19:38
> *À :* Qin Wu <[e-mail]>; Mahesh Jethanandani <
> [e-mail]>; BOUCADAIR Mohamed INNOV/NET <
> [e-mail]>
> *Cc :* [e-mail]
> *Objet :* RE: [netmod] Long trees RE: Next steps for
> draft-ietf-netmod-rfc8407bis
>
>
>
> Hi Med,
>
>
>
> In my personal experience, I have found the YANG tree included in the IETF
> RFCs/I-Ds useful only when they are complete, even if they are too long
>
> *[Med] I agree that having readily available full trees is useful, however
> the question is whether it should be embedded in the RFC text or would
> having stable links to access such trees be much more convenient? Note also
> that when the tree is too long, there are better places to display them for
> better user experience (control views, etc.), which we don’t have with the
> txt version.*
>
>
>
> In RFC8795 you can find an example of a too-long YANG tree which I am
> using quite often
>
>
>
> *[Med] If the Datatracker includes a link to the tree or 8795 includes a
> stable pointer to the full tree without the editing limitations of IETF
> docs, the experience would be the same, if not better. No?*
>
>
>
>
>
> I have found YANG trees with unexpanded grouping almost impossible to use.
> In draft-ietf-teas-yang-te you can find an example of a YANG tree with
> unexpanded grouping which I am not using at all. In this case, I refer to
> the YANG catalog to get the complete tree
>
>
>
> *[Med] ACK.*
>
>
>
> I have also found the YANG tree pieces almost useless (even if much better
> than the YANG trees with unexpanded grouping) without some overview.
>
>
>
> *[Med] Not having an overview to describe the overall structure and help
> readers navigate among all the various levels is a bug of these specs, IMO.
> The narrative part of the spec is supposed to help readers digest the
> structure and zoom in/out when diving into specifics. I think that we need
> collectively to better explain the rationale of a module design and
> articulating the various parts of a module. The use of subtrees for too
> long trees is a means to help structure the description sections.*
>
>
>
> RFC8348 is an example of YANG tree pieces which I am using very rarely. In
> most of the cases, I refer to the YANG catalog to get the complete tree
>
> *[Med] ACK.*
>
>
>
> I am wondering whether the issue of YANG tree too-long could be resolved
> by updating the IETF tooling. For example, I have noted that the html-ized
> version of the I-Ds is now working well with artwork exceeding the 72
> characters limit …
>
>
>
> Maybe the html or html-ized version of the I-D/RFC might include the
> jstree pyang output instead of the tree pyang output
>
>
>
> *[Med] Fully agree that tooling is the way to go here. Having a stable
> pointer to the tree (including displaying it from the Datatracker metadata)
> would achieve that objective.*
>
>
>
> *Back to the txt version, here is an updated version of the reco (for
> further discussion):*
>
>
>
> ==
>
> 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 document.  A stable pointer to retrieve the
>
>    full tree MAY be included.
>
>
>
>    The document SHOULD include the following note if the full tree is
>
>    not included:
>
>
>
>       -- If no stable pointer to retrieve the tree is included
>
>
>
>       The full tree diagram of the module can be generated using,
>
>       e.g., the "pyang" tool. That tree is not included here because
>
>       it is too long (Section 3.4 of [RFCXXXX]). Instead, subtrees
>
>       are provided for the reader's convenience.
>
>
>
>       -- If a stable pointer to retrieve the tree is included
>
>
>
>       The full tree diagram of the module can be retrieved at
>
>       <stable_url_ref>. That tree is not included here because it is too
>
>       long (Section 3.4 of [RFCXXXX]). Instead, subtrees are provided
>
>       for the reader's convenience.
>
>
>
>    These guidelines take precedence over the generic guidance in
>
>    Section 3 of [RFC8340].
>
> ==
>
>
>
> My 2 cents
>
>
>
> Italo
>
>
>
> *From:* Qin Wu <[e-mail]>
> *Sent:* giovedì 29 febbraio 2024 02:51
> *To:* Mahesh Jethanandani <[e-mail]>;
> [e-mail]
> *Cc:* [e-mail]
> *Subject:* Re: [netmod] Long trees RE: Next steps for
> draft-ietf-netmod-rfc8407bis
>
>
>
> +1,  a few thoughts to share.
>
>
>
> I know this is tricky question related to tooling or artifact generation
> and representation.
>
> I am wondering whether we can make YANG tree diagram in a "collapsed"
> state where all the Leaf nodes and only leaf nodes are hidden from view
> until its parent node is expanded, which can improve readability of the
> tree diagram,
>
> In many cases can greatly reduce the size of YANG tree diagram, make it
> fit into one page.
>
>
>
> Moving compete tree diagram or artifacts is another option we can pursue.
> Also generating YANG tree along with YANG file in
> https://github.com/YangModels/yang/tree/main/standard/ietf
>
> Is another option we can take a look at.
>
>
>
> -Qin
>
> *发件人**:* netmod [mailto:[e-mail] <[e-mail]>]
>  *代表 *Mahesh Jethanandani
> *发送时间:* 2024年2月29日 7:02
> *收件人:* [e-mail]
> *抄送:* [e-mail]
> *主题:* Re: [netmod] Long trees RE: Next steps for
> draft-ietf-netmod-rfc8407bis
>
>
>
> I would agree with Andy that it is not clear how long is “too long”.
>
>
>
> BGP YANG model, which is perhaps one of the biggest models at 150 pages
> long, has multiple tree diagrams none of which are more than one page long.
>
>
>
> If the complete tree diagram is too long, could it moved to the Appendix,
> instead of banishing it from the document completely? Sorry Jan, but I hope
> no one is cutting down trees to read the entire tree diagram. Sometimes,
> albeit rarely, it is helpful to have the complete tree diagram handy to
> reference where a particular node is in the tree.
>
>
>
> Cheers.
>
>
>
> On Feb 28, 2024, at 8:29 AM, [e-mail] wrote:
>
>
>
> Hi Jan,
>
>
>
> Thanks for the comments.
>
>
>
> Here is a first attempt to address the long trees point while taking into
> account expanded/unexpanded uses:
>
>
>
> 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 too
>
>    long, the diagram SHOULD be split into several smaller diagrams.  If
>
>    the complete tree diagram is too long even with groupings unexpanded
>
>    (Section 2.2 of [RFC8340]), authors SHOULD NOT include it in the
>
>    document.
>
>
>
>    These guidelines take precedence over the generic guidance in
>
>    Section 3 of [RFC8340].
>
>
>
> For convenience a diff for the proposed change can be seen
> https://author-tools.ietf.org/api/iddiff?url_1=https://boucadair.github.io/rfc8407bis/draft-ietf-netmod-rfc8407bis.txt&url_2=https://boucadair.github.io/rfc8407bis/long-trees/draft-ietf-netmod-rfc8407bis.txt
>
>
>
> Cheers,
>
> Med
>
>
>
> *De :* Jan Lindblad <[e-mail]>
> *Envoyé :* mercredi 28 février 2024 15:21
> *À :* BOUCADAIR Mohamed INNOV/NET <[e-mail]>
> *Cc :* [e-mail]
> *Objet :* Re: [netmod] Next steps for draft-ietf-netmod-rfc8407bis
>
>
>
> Med, author team,
>
>
>
> Thank you for taking the time to get this work done, and well done! This
> is one of those fundamental bricks that saves time and improves quality for
> the entire YANG community.
>
>
>
> I read the -09 version and like what I see. I have a couple of minor
> suggestions you might consider.
>
>
>
> + In section 3.4 about tree diagrams, the section text is already
> advocating intermixing smaller tree snippets with explanations (which is
> great), but I wish we could say that
>
> tree diagrams of entire modules SHOULD NOT be included. Just a waste of
> forest and attention span, imho.
>
>
>
> + In section 4.2 about choice of prefixes, it is said that "Prefix values
> SHOULD be short but are also likely to be unique." I used to say the same
> thing. In recent years, however, I have started to stress the importance of
> uniqueness much more. I'd say something like "Prefix values SHOULD be
> selected carefully to be unique, and ideally not too long." The reason for
> my change is I have met several engineers who have been deeply confused (to
> the point of costing real money) when the same prefix has shown up in
> multiple places. It's just an unnecessary part of the learning curve
> associated with YANG.
>
>
>
> In fact, I have started to recommend people to set the prefix to equal the
> module name. This also solves another problem, which is that the "prefixes"
> you see in RESTCONF are module names, and the confusion of what to use
> where is sometimes suffocating. I understand if many think I'm going
> overboard here, but when we pretend that modules don't have prefixes, only
> module names, there is a lot less friction in learning the ropes.
>
>
>
> + In section 4.6.2 regarding useless (in YANG Context) functions in the
> XPath function library, it is said that the "YANG compiler" should return
> false, etc. Better wording might be that the XPath execution environment
> (or something) should return false, etc. The YANG compiler is not even
> running when the calls to those functions are happening.
>
>
>
> + In section 4.11.5 regarding booleans, it is said that booleans can take
> values true and false. This is true in mathematics :-) but in YANG a
> boolean leaf can additionally take the "value" of "not set". Actually, "not
> set" is a possibility for leafs in general, unless it is declared mandatory
> true, or has a default. In my experience, one of the most common YANG
> modeling issues is when people model a leaf foo, which isn't mandatory, has
> no default and the description statement does not say what happens if the
> leaf is not set. In many cases, there is a sort of natural meaning, but
> with booleans leafs in particular, the absence of the leaf is typically
> highly ambiguous. I think this hole merits a recommendation clause in the
> I-D.
>
>
>
> Best Regards,
>
> /jan
>
>
>
>
>
>
>
> On 28 Feb 2024, at 10:51, [e-mail] wrote:
>
>
>
> Hi all,
>
> I think that this version is ready for the WGLC.
>
> The document fully covers the items promised when requesting adoption [1].
> As listed in the ACK section, we also solicited and integrated feedback
> from many yangdoctors, solicited SAAG WG to review the security text, etc.
> Refer to 1.1 for a comprehensive list of the changes.
>
> Cheers,
> Med
>
> [1] Slide#7 of
> https://datatracker.ietf.org/meeting/117/materials/slides-117-netmod-7-guidelines-for-authors-and-reviewers-of-documents-containing-yang-data-models-00
>
>
>
> -----Message d'origine-----
> De : I-D-Announce <[e-mail]> De la part de
> [e-mail]
> Envoyé : mercredi 28 février 2024 10:01
> À : [e-mail]
> Cc : [e-mail]
> Objet : I-D Action: draft-ietf-netmod-rfc8407bis-09.txt
>
> Internet-Draft draft-ietf-netmod-rfc8407bis-09.txt is now available.
> It is a work item of the Network Modeling (NETMOD) WG of the IETF.
>
>   Title:   Guidelines for Authors and Reviewers of Documents
> Containing YANG Data Models
>   Authors: Andy Bierman
>            Mohamed Boucadair
>            Qin Wu
>   Name:    draft-ietf-netmod-rfc8407bis-09.txt
>   Pages:   84
>   Dates:   2024-02-28
>
> Abstract:
>
>   This memo provides guidelines for authors and reviewers of
>   specifications containing YANG modules, including IANA-maintained
>   modules.  Recommendations and procedures are defined, which are
>   intended to increase interoperability and usability of Network
>   Configuration Protocol (NETCONF) and RESTCONF protocol
>   implementations that utilize YANG modules.  This document obsoletes
>   RFC 8407.
>
>   Also, this document updates RFC 8126 by providing additional
>   guidelines for writing the IANA considerations for RFCs that
> specify
>   IANA-maintained modules.
>
> The IETF datatracker status page for this Internet-Draft is:
> https://eur03.safelinks.protection.outlook.com/?url=https%3A%2F%2Fdata
> <https://data/>
> tracker.ietf.org%2Fdoc%2Fdraft-ietf-netmod-
> rfc8407bis%2F&data=05%7C02%7Cmohamed.boucadair%40orange.com%7C51672231
> 30c943a5a4c608dc383bce6b%7C90c7a20af34b40bfbc48b9253b6f5d20%7C0%7C0%7C
> 638447076716455966%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjo
> iV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C0%7C%7C%7C&sdata=s5VX9Hb%2Fl
> P9v5QurysF69syyEyba9yYss7xd7K5E2FE%3D&reserved=0
>
> There is also an HTML version available at:
> https://eur03.safelinks.protection.outlook.com/?url=https%3A%2F%2Fwww
> <https://www/>.
> ietf.org%2Farchive%2Fid%2Fdraft-ietf-netmod-rfc8407bis-
> 09.html&data=05%7C02%7Cmohamed.boucadair%40orange.com%7C5167223130c943
> a5a4c608dc383bce6b%7C90c7a20af34b40bfbc48b9253b6f5d20%7C0%7C0%7C638447
> 076716464395%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luM
> zIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C0%7C%7C%7C&sdata=%2Br3nHahSq8OV24f
> hFxBkJaqY43Q0GUxcbPZSFhji4uk%3D&reserved=0
>
> A diff from the previous version is available at:
> https://eur03.safelinks.protection.outlook.com/?url=https%3A%2F%2Fauth
> <https://auth/>
> or-tools.ietf.org%2Fiddiff%3Furl2%3Ddraft-ietf-netmod-rfc8407bis-
> 09&data=05%7C02%7Cmohamed.boucadair%40orange.com%7C5167223130c943a5a4c
> 608dc383bce6b%7C90c7a20af34b40bfbc48b9253b6f5d20%7C0%7C0%7C63844707671
> 6470644%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLC
> JBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C0%7C%7C%7C&sdata=zo%2FrtFJrYJkJXOceIpzR
> mlGAQF2c8m9Z%2F0vShl5o8gQ%3D&reserved=0
>
> Internet-Drafts are also available by rsync at:
> rsync.ietf.org::internet-drafts
>
>
>
>
> ____________________________________________________________________________________________________________
> 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.
>
> _______________________________________________
> netmod mailing list
> [e-mail]
> https://www.ietf.org/mailman/listinfo/netmod
>
>
>
> ____________________________________________________________________________________________________________
>
> 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.
>
> _______________________________________________
> netmod mailing list
> [e-mail]
> https://www.ietf.org/mailman/listinfo/netmod
>
>
>
>
> Mahesh Jethanandani
>
> [e-mail]
>
>
>
>
>
>
>
>
>
>
>
> ____________________________________________________________________________________________________________
>
> 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.
>
> _______________________________________________
> 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
>