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

[Andy Bierman <[e-mail]>]

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]>
> *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,
> see
> 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] 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://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
>
>
>
> Cheers,
>
> Med
>
>
>
> *De :* Lou Berger <[e-mail]> <[e-mail]>
> *Envoyé :* mardi 1 octobre 2024 00:24
> *À :* [e-mail]; [e-mail]
> *Cc :* Kent Watsen <[e-mail]> <[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 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]>
> <[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 to [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]
> To unsubscribe send an email to [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.
>
>