Subject: [Gen-art] draft-ietf-sacm-requirements-15.txt

From: Francis Dupont <[email-masked]>
Date: Sun, 11 Jun 2017 11:13:28 +0200

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-sacm-requirements-15.txt
Reviewer: Francis Dupont
Review Date: 20170607
IETF LC End Date: 20170605
IESG Telechat date: unknown

Summary: Almost Ready

Major issues: None

Minor issues: ambiguous uses of lowercase keywords:
RFC 2119 is very ambiguous about the required case of keywords so even
of 1.1 includes a "uppercase keyword only" statement I strongly recommend
to avoid use of lowercase keywords in numbered requirements (and to
add a statement about this in 1.1). Note there are a few "required" and
at least a "shall". In a few case this should avoid further questions
about whether to promote a lower case verb (e.g., a may) to a keyword.

Nits/editorial comments: 
 - ToC page 2 and 3 page 15: Acknowledgements -> Acknowledgments

 - 1 page 2: expand the SACM abbrev at the first use in the boday

 - 2.1 page 5 G-002: first example of a lowercase keyword (a must)
  which is both ambiguous and a candidate to uppercase (note as
  there is no keywords in G-002 it is even a strong candidate).

 - 2.1 page 5 G-003: ambiguous "must" in "Scalability must be addressed..."
  (I propose to replace it by "has to")

  I counted 30 ambiguous keywords in numbered requirements
  (I can give details if you need)

 - 2.1 page 6 (G-006 & G-009 (twice)), 2.3 page 9 (IM-006), 2.6 page 14
  (T-004):  i.e. -> i.e.,

 - 2.2 page 8 (ARCH-007), 2.4 pages 10 (DM-002) and 11 (DM-004, DM-010
  and DM-011), 2,5 page 13 (OP-007 (twice)), 2.6 page 14 (T-003 and T-005),
  5.2 page 17:  e.g. -> e.g.,

 - 2.6 page 14 (proposal): hyperText -> hypertext
  BTW HTTP is a well known abbrev so you can simply leave HTTP
  (cf http://www.rfc-editor.org/materials/abbrev.expansion.txt)

 - 5 pages 15-17: lowercase keywords (so not to be interpreted as keywords)
  are fine here as there are not in numbered requirements.

 - 5.2 page 17: unecessary -> unnecessary

 - 7.1 page 18: draft-ietf-sacm-terminology is (intented to be)
  informational so to have it as a normative reference is questionable.
  Same for RFC 5209 and RFC 7632. Note according to the RFC 7322 the
  rule for normative vs informative references is flexible so you can
  argue these documents bring important or even critical information.

 - Addresses page 10: (more for the RFC Editor) please try to move the
  title to the next page.

Regards

[email-masked]

---

From: Alissa Cooper <[email-masked]>
Date: Wed, 21 Jun 2017 12:44:12 -0400

Francis, thank you for your review. I have indicated in my ballot that no response has been received yet.

Alissa

> On Jun 11, 2017, at 5:13 AM, Francis Dupont <[email-masked]> wrote:
> 
> _______________________________________________
> Gen-art mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/gen-art

---

From: "Nancy Cam-Winget (ncamwing)" <[email-masked]>
Date: Sun, 25 Jun 2017 23:27:36 +0000

Thanks for including the Gen-Art feedback.
For some reason, I have not received either the gen-art nor the “discuss” so am trying to resolve and respond through this 
Email (for the gen-art) and will see on how to better respond to the “discuss” in a bit.

To Alissa’s comment: I have made the general substitution of “transport” to “transfer” where applicable (apologies as the inconsistency is an oversight).

For gen-art, please see below with my annotations marked as “[NCW]”:

On 6/21/17, 9:44 AM, "Alissa Cooper" <[email-masked]> wrote:

    Alissa
    
    > about whether to promote a lower case verb (e.g., a may) to a keyword.
[NCW] There was another comment/question to the actual applicability of
2119.  As this is a requirements document, the uppercase keywords are meant
to indicate what is an actual requirement (MUST) vs. recommendation (SHOULD);
as such, I will remove the 2119 and update the requirements language to better
reflect intent.

    > - ToC page 2 and 3 page 15: Acknowledgements -> Acknowledgments
[NCW] Done.

    > - 1 page 2: expand the SACM abbrev at the first use in the boday
[NCW] Done.

    >  there is no keywords in G-002 it is even a strong candidate).
[NCW] candidates for adoption have to ensure interoperability, so I’ve made this a capital MUST.

    >  (I propose to replace it by "has to")
[NCW] Fair enough, though the MUST is to reflect that is has to address this…but the recommendation to include a section should suffice so will have the “MUST” to “has to”

    >  (I can give details if you need)
[NCW] Hopefully with new “intent” of use of capitalization should have helped, if not, do please let me know.

    >  (cf http://www.rfc-editor.org/materials/abbrev.expansion.txt)
[NCW] LoL….I was told to add it in a previous review, but will remove it (again since I can reference the link above!) 
    >  argue these documents bring important or even critical information.
[NCW] Oops, will move them to informational.  Though, I will leave 7632 as they
were used to exemplify and tease out the requirements.