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

[Mahesh Jethanandani <[e-mail]>]

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 <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] <mailto:[e-mail]>>; [e-mail] <mailto:[e-mail]>; [e-mail] <mailto:[e-mail]>; Jan Lindblad (jlindbla) <[e-mail] <mailto:[e-mail]>>
> Cc : Kent Watsen <[e-mail] <mailto:[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] <mailto:[e-mail]>> 
> Envoyé : mardi 1 octobre 2024 13:37
> À : BOUCADAIR Mohamed INNOV/NET <[e-mail] <mailto:[e-mail]>>; [e-mail] <mailto:[e-mail]>; [e-mail] <mailto:[e-mail]>; Jan Lindblad (jlindbla) <[e-mail] <mailto:[e-mail]>>
> Cc : Kent Watsen <[e-mail] <mailto:[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://mailarchive.ietf.org/arch/msg/netmod/0Q0YiyNi15V-Szzf5awLVh-15_c/ <https://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] <mailto:[e-mail]> wrote:
> Hi Lou,
>  
> 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/ <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.
>  
> The candidate change was shared with the WG prior to IETF#119:https://mailarchive.ietf.org/arch/msg/netmod/x9aex0PO-KARyg5FtzjLNYrIpLY/ <https://mailarchive.ietf.org/arch/msg/netmod/x9aex0PO-KARyg5FtzjLNYrIpLY/>
> 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] <mailto:[e-mail]>; [e-mail] <mailto:[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 in https://www.rfc-editor.org/rfc/rfc8340#section-3.3 <https://www.rfc-editor.org/rfc/rfc8340#section-3.3> which 
> 
> (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/ <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/ <https://mailarchive.ietf.org/arch/msg/netmod/1LDpkPi_C8cqktc7HXSZgyPDCBE/>
>  
> Kent & Lou (as co-chairs)
>  
>  
>  
>  
>  
> _______________________________________________
> netmod mailing list
> [e-mail] <mailto:[e-mail]>
> https://www.ietf.org/mailman/listinfo/netmod <https://www.ietf.org/mailman/listinfo/netmod>
>  
> 
> 
> 
> _______________________________________________
> netmod mailing list -- [e-mail] <mailto:[e-mail]>
> To unsubscribe send an email to [e-mail] <mailto:[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 to [e-mail] <mailto:[e-mail]>
Mahesh Jethanandani
[e-mail]