Re: [RTG-DIR] [netmod] RtgDir review: Review of draft-ietf-netmod-yang-tree-diagrams-05.txt

Hi Stig,

Thank you for your review!  Comments inline.

Stig Venaas <stig@venaas.com> wrote:
> Hello,
> 
> I have been selected as the Routing Directorate reviewer for this
> draft. The Routing Directorate seeks to review all routing or
> routing-related drafts as they pass through IETF last call and IESG
> review, and sometimes on special request. The purpose of the review is
> to provide assistance to the Routing ADs. For more information about
> the Routing Directorate, please see
> http://trac.tools.ietf.org/area/rtg/trac/wiki/RtgDir
> 
> Although these comments are primarily for the use of the Routing ADs,
> it would be helpful if you could consider them along with any other
> IETF Last Call comments that you receive, and strive to resolve them
> through discussion or by updating the draft.
> 
> Document: draft-ietf-netmod-yang-tree-diagrams-05.txt
> Reviewer: Stig Venaas
> Review Date: 2018-01-29
> IETF LC End Date: 2018-02-07
> Intended Status: Best Current Practice
> 
> Summary:
> This document is basically ready for publication, but has nits that
> should be considered prior to publication.
> 
> Comments:
> The draft is well written and ready for publication except for perhaps
> two nits. My YANG skills are a bit limited though, so it is possible
> that I may have missed issues.
> 
> Major Issues:
> No major issues found.
> 
> Minor Issues:
> No minor issues found.
> 
> Nits:
> In the introduction it says:
>    Today's common practice is to include the definition of the syntax
>    used to represent a YANG module in every document that provides a
>    tree diagram.  This practice has several disadvantages and the
>    purpose of the document is to provide a single location for this
>               ^^^^
>    definition.  It is not the intent of this document to restrict future
>    changes, but rather to ensure such changes are easily identified and
>    suitably agreed upon.
> 
> It would be better to say "this document".

Thanks, fixed in the source!

> In section 2 it says:
>    A module is identified by "module:" followed the module-name.
> 
> In the introduction [RFC7223] Section 3 is given as an example
> tree diagram, but this does not start with "module:". Would
> another example be better?

First of all, the example is legal since the text says:

    Module trees may be included in a document as a whole, by one or
    more sections, or even subsets of nodes.

I also think the example is fine, since it is in the introduction,
and, well, just an example of what current trees look like.

> It might also be good to have a
> richer example that makes use of most of the defined symbols.

I'm not sure what example we would use for this.  We believe that the
current examples in the document are "good enough".

/martin

> 
> Otherwise the document looks great to me.
> 
> Stig
> 
> _______________________________________________
> netmod mailing list
> netmod@ietf.org
> https://www.ietf.org/mailman/listinfo/netmod
> 