Re: [netmod] I-D Action: draft-ietf-netmod-yang-tree-diagrams-02.txt size

[Andy Bierman <[e-mail]>]

Hi,

I do not agree that 6087bis should contain every micro-managed detail
that could possibly pertain to YANG, such as what section the
YANG diagram belongs in, or what exact pyang settings should be
used in every possible usage scenario.

It seems obvious that a 36 page tree diagram for a 47 page module is absurd.
Use a lower tree depth or manually replace subtrees with ...


Andy


On Fri, Oct 27, 2017 at 5:36 AM, Lou Berger <[e-mail]> wrote:

> Juergen,
>
>
> On 10/27/2017 7:57 AM, Juergen Schoenwaelder wrote:
> > On Fri, Oct 27, 2017 at 07:04:24AM -0400, Lou Berger wrote:
> >>> We should encourage authors to split large diagrams into manageable
> >>> pieces. Sometimes suppressing lots of statistics counters helps,
> >>> sometimes showing which groupings are used instead of their expansion
> >>> helps. Sometimes it helps to separate major branches of a tree and to
> >>> discuss them separately. We should encourage authors to do these
> >>> things.
> >> I agree with this too, and this was the goal of the current text.
> >>> Perhaps we need to state clearly that it is not necessary to
> >>> include a plain fully expanded tree diagram.
> >> Please propose text for the draft!
> > Personally, I think usage guidelines do not belong into the yang tree
> > document in the first place. Having the document just define what tree
> > diagrams are would be my preference, leaving usage guidelines to our
> > guidelines document.
>
> Having a guidelines document that evolves naturally over time is just
> fine, much like coding conventions.  But trying to bundle or wait for
> the convention update both increases the cost of doing guidelines and
> leaves a time window when the guidelines are not documented.  While in
> some cases this may just fine, I think in this case it would leave much
> "folklore" undocumented.  In other words, I think we should capture the
> guidelines as best as we can in this document. As I think I've stated
> publicly before, I also think the we as WG have to figure out how to
> work more "nimbly" by resisting the temptation to have big documents
> that cover all aspects of the particular topic at once.
>
> I do think your observation on having two sets of guidelines is correct
> and not a good thing.  We can address this quite simply by (a) marking
> this document as updating 6087bis and (b) ensuring we have a full
> replacement to the tree guidelines provided in that document.
>
> >  Section 3.4 of 6087bis talks about tree diagrams
> > and I would prefer to have guidelines text in one place. But perhaps a
> > clear separation of 'here is stuff' from 'this is how we suggest to
> > use stuff' is difficult in practice. But what we have here is that we
> > now have two places where advice is given how to use stuff...
> >
> > That said, RFC 6087bis says:
> >
> >    YANG tree diagrams provide a concise representation of a YANG module,
> >    and SHOULD be included to help readers understand YANG module
> >    structure. Tree diagrams MAY be split into sections to correspond to
> >    document structure.
> >
> > With all the capital letters in place, the text might cause people to
> > draw the wrong conclusion that they have to include plain tree
> > diagrams. The text does not give a good explanation when a split
> > should be considered or that a full plain dump may not be needed or
> > where to find good examples of diagrams broken into pieces. The text
> > in the yang tree diagram document is actually better in this regard.
> >
> > The example in section 3.4 of RFC 6087bis is actually repeating the
> > non-NDMA /foo /foo-state style, well, we are getting off topic.
> >
> >>> In the case of draft-ietf-teas-yang-te-topo-12.txt, the fully expanded
> >>> tree diagram (36 pages) is simply in no good relation with the size of
> >>> the definitions (47 pages). And the authors of this document do the
> >>> right thing, they provide overview diagrams that leave out lots of
> >>> details and that are comprehensible. So is it valuable to keep the
> >>> full dump in the document?
> >> I personally don't think so, and questioned its usefulness.  I also
> >> suggested moving to an appendix if they really wanted to keep it.  For
> >> whatever reason they decided they wanted to keep it which is, of course,
> >> within their purview.
> >>
> >> So, I think the question for us is: what, beyond the change you suggest
> >> above, add to the tree draft to cover cases where authors really want to
> >> include such long trees?
> > At the end, WGs decide with the input from the authors, reviewers
> > etc. and not everything needs to have rules that we cast into RFCs.
> absolutely agree!
>
> Cheers,
> Lou
> > Perhaps we are better off having a few questions and answers on the
> > FAQ concerning tree diagrams.
> >
> > /js
> >
>
> _______________________________________________
> netmod mailing list
> [e-mail]
> https://www.ietf.org/mailman/listinfo/netmod
>