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

[Benoit Claise <[e-mail]>]

Dear all,

I tend to agree with Andy here.
What are the key advantages to have some YANG tree diagram rules here? 
We never know in advance what people are looking for in that full tree. 
Sometimes, it's a simple grep.
And if it's too long/not useful, people will simply skip it
We are not even saving trees, as (I guess that) people don't print out 
RFCs any longer.

Regards, Benoit

On 10/14/2024 1:23 PM, Andy Bierman wrote:
> 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://author-tools.ietf.org/api/iddiff?url_1=https://netmod-wg.github.io/rfc8407bis/draft-ietf-netmod-rfc8407bis.txt&url_2=https://netmod-wg.github.io/rfc8407bis/long-trees/draft-ietf-netmod-rfc8407bis.txt>
>
>     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]
>     <mailto:[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://author-tools.ietf.org/api/iddiff?url_1=https://netmod-wg.github.io/rfc8407bis/draft-ietf-netmod-rfc8407bis.txt&url_2=https://netmod-wg.github.io/rfc8407bis/long-trees/draft-ietf-netmod-rfc8407bis.txt>
>           * PR:https://github.com/netmod-wg/rfc8407bis/pull/70/files
>
>         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,
>         seehttps://mailarchive.ietf.org/arch/msg/netmod/0Q0YiyNi15V-Szzf5awLVh-15_c/
>
>         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]:
>
>             Hi Lou,
>
>              1. The comment that triggered the change and companion
>                 thread where this was discussed and changes proposed
>                 can be seen at:
>
>             https://mailarchive.ietf.org/arch/msg/netmod/-b2HX0XUK49qJB19LHu6MC0D9zc/.
>
>             Please note that for html version can still include the
>             long tree,
>
>             The tooling may evolve in the future to provide better
>             rendering
>
>             of too long trees.  This tooling may offer (but not
>             limited to),
>
>             unfold trees, control of expanded views, ease navigation among
>
>             various levels of a tree, support of hyperlinks, etc. When
>             such a
>
>             tooling is available, too long trees can be displayed in
>             the HTML
>
>             version of documents that include such trees.
>
>              1. The candidate change was shared with the WG prior to
>                 IETF#119:https://mailarchive.ietf.org/arch/msg/netmod/x9aex0PO-KARyg5FtzjLNYrIpLY/
>              2. The thread was open for almost 1 month and a
>                 half:https://author-tools.ietf.org/iddiff?url1=draft-ietf-netmod-rfc8407bis-09&url2=draft-ietf-netmod-rfc8407bis-10&difftype=--html
>                 <https://author-tools.ietf.org/iddiff?url1=draft-ietf-netmod-rfc8407bis-09&url2=draft-ietf-netmod-rfc8407bis-10&difftype=--html>
>
>             Cheers,
>
>             Med
>
>             *De :*Lou Berger<[e-mail]> <mailto:[e-mail]>
>             *Envoyé :*mardi 1 octobre 2024 00:24
>             *À :*[e-mail];[e-mail]
>             *Cc :*Kent Watsen<[e-mail]>
>             <mailto:[e-mail]>
>             *Objet :*Re: [netmod] Re: WGLC on draft-ietf-netmod-rfc8407bis
>
>             Hi,
>
>             I have a late comment as contributor on this draft (based
>             on a co-chair discussion).
>
>             Looking at the diff relative of section 3.4 to the
>             original document, I think the idea of referencing a URL
>             versus an appendix is a bad idea. The new text in question:
>
>             " 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."
>
>             I prefer the original
>             inhttps://www.rfc-editor.org/rfc/rfc8340#section-3.3which
>
>             (a) does not have conformance language and
>
>             (b) keeps the information as available as the document
>             itself by including the long diagram in an appendix.
>
>             I would like to see this section reverted to the original.
>
>             Authors,
>
>             What is the motivation for the change to URLs and making
>             this a "SHOULD NOT"?
>
>             Thanks,
>
>             Lou
>             ¶
>             <https://datatracker.ietf.org/doc/html/draft-ietf-netmod-rfc8407bis-17#section-3.4-1>
>
>             On 9/20/2024 4:03 PM, Kent Watsen wrote:
>
>                 This WGLC has successfully closed. The document has
>                 moved to the WG State "WG Consensus: Waiting for
>                 Write-Up”.
>
>                 Thank you everyone, especially Med, for your diligence
>                 in resolving issues!
>
>                 The next step is the Shepherd write-up.  Would anyone
>                 in the WG be willing to volunteer to help out with it?
>
>                 Thanks,
>
>                 Kent and Lou (chairs)
>
>
>
>
>                     On May 6, 2024, at 9:57 AM, Kent
>                     Watsen<[e-mail]>
>                     <mailto:[e-mail]>wrote:
>
>                     This email begins a two-week WGLC on:
>
>                     Guidelines for Authors and Reviewers of Documents
>                     Containing YANG Data Models
>
>                     https://datatracker.ietf.org/doc/draft-ietf-netmod-rfc8407bis/
>
>                     Please take time to review this draft and post
>                     comments by May 20.
>
>                     Favorable comments are especially welcomed.
>
>                     No IPR has been declared for this document:
>
>                     https://mailarchive.ietf.org/arch/msg/netmod/1LDpkPi_C8cqktc7HXSZgyPDCBE/
>
>                     Kent & Lou (as co-chairs)
>
>                     _______________________________________________
>                     netmod mailing list
>                     [e-mail]
>                     https://www.ietf.org/mailman/listinfo/netmod
>
>
>
>
>                 _______________________________________________
>
>                 netmod mailing list [e-mail]
>
>                 To unsubscribe send an email [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.
>
>         ____________________________________________________________________________________________________________
>
>         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] <mailto:[e-mail]>
>         To unsubscribe send an email [e-mail]
>         <mailto:[e-mail]>
>
>     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]
> To unsubscribe send an email [e-mail]