[mpls] Gen-ART Last Call review of draft-ietf-mpls-msd-yang-05

[Paul Kyzivat <[e-mail]>]

I am the assigned Gen-ART reviewer for this draft. The General Area
Review Team (Gen-ART) reviews all IETF documents being processed
by the IESG for the IETF Chair.  Please treat these comments just
like any other last call comments.

For more information, please see the FAQ at

<https://trac.ietf.org/trac/gen/wiki/GenArtfaq>.

Document: draft-ietf-mpls-msd-yang-05
Reviewer: Paul Kyzivat
Review Date: 2024-05-27
IETF LC End Date: 2024-06-04
IESG Telechat date: ?

Summary:

This draft is on the right track but has open issues, described in the 
review.

Disclaimer:

This reviewer is "YANG challenged". Hence I have not verified the syntax 
or semantics of the YANG content. I trust there has been or will be a 
separate review by a YANG expert.

ISSUES: 3
NITS: 1

1) ISSUE - General

I find the language in this document to be extremely difficult to 
follow. (For instance, see the confusing language cited in the next 
issue.) The main problem is that it is formally referencing and defining 
terms/entities named using sequences of words and acronyms including 
spaces. (This includes YANG entities, IANA registry table names, and the 
names of entries in IANA registries.)

These terms are used in descriptions with nothing to distinguish them 
from the surrounding text. Hence it becomes a struggle to parse the 
text. I strongly recommend revising the document to syntactically set 
off the formal names of the entities being defined and referenced from 
the surrounding text. For instance: 'IGP MSD-Types'

2) ISSUE - Confusing language in Section 1

I can't parse: "... defines the identities for Maximum SID Depth (MSD) 
Types as the IANA the IGP MSD-Types registry."

I still can't follow it even if I make the change I requested above:

"... defines the identities for Maximum SID Depth (MSD) Types as the 
IANA the 'IGP MSD-Types' registry."

. I *think* you might mean:

"... defines the identities for 'Maximum SID Depth (MSD)' Types in the 
IANA 'IGP MSD-Types' registry." But I am far from certain of this.

3) ISSUE - Possible missing IANA action

Section 4 defines a YANG module named 'iana-msd-types'. I *think* there 
is an intent to add this as a new entry in the IANA registry 'IGP 
MSD-Types'. But I don't find anything that does this. (I would expect 
something more in IANA Considerations.)

4) NIT

The document heading shows "Workgroup: Internet" but shouldn't it be the 
MPLS WG?