Subject: [Gen-art] Gen-art LC review: draft-ietf-v6ops-enterprise-incremental-ipv6-05

From: Robert Sparks <[email-masked]>
Date: Thu, 05 Jun 2014 14:00:49 -0500

I am the assigned Gen-ART reviewer for this draft. For background on
Gen-ART, please see the FAQ at

<http://wiki.tools.ietf.org/area/gen/trac/wiki/GenArtfaq>.

Please resolve these comments along with any other Last Call comments
you may receive.

Document: draft-ietf-v6ops-enterprise-incremental-ipv6-05
Reviewer: Robert Sparks
Review Date: 5 June 2014
IETF LC End Date: 9 June 2014
IESG Telechat date: not yet scheduled

Summary: This draft is basically ready for publication as an 
Informational RFC,
but has nits that should be considered before publication.

I had a mixed overall impression after my first read-through of this draft.

Overall, the list of issues to consider, and the compendium of 
references is very useful, but there are large stretches of text that 
really aren't helping the reader, and they make the good stuff harder to 
see.

I encourage the group to take one more editorial pass, focusing on 
removing as much text as possible without losing the message.

Please help the IESG and the RFC-Editor out: the shepherd's writeup 
should say something about why deviating from the style guide's 
restriction on number of authors is is appropriate for this document.

Here are specific nits to consider in document order:

The first paragraph of section 1.3 starts talking about phases as if 
they've already been described. As written, it says that beginning with 
the External Phase is recommended in RFC5211. But the words "External 
Phase" do not appear in 5211, and its not clear on a quick read exactly 
what in 5211 you were hoping to point out here.  Please introduce the 
phases before this point, and change the callout to 5211 to make it more 
clear how what 5211 is saying ties into this document.

Why is "Other Phases" capitalized in 2.1? The number of phases defined 
in this document is small - I suspect this text is older and left room 
for the group to decide to define more phases. Consider just listing 
what you ended up with explicitly.

Section 2.1 contains sentences like "The project manager will need to 
spend some time on planning." That is obvious, and you've already 
established that planning needs to happen. This paragraph (perhaps much 
of this section) would be improved by removing as much text as you can. 
It already speaks mostly in terms of the benefits of planning. Making 
that a more explicit goal in the writing structure would help identify 
what can be taken away without losing the message. Overall, trying to 
describe what good project management entails is a bit out of place. 
Perhaps you should just say "This requires good project management skills"?

In 2.2.2 you say "Applications should be made to use APIs". That seems 
an odd construct for an IETF document. Perhaps you could observe, rather 
than command, here? Would saying something like "Applications that use 
APIs to hide the specifics ... will be easier to take through the 
migration" make the point?

In 2.3, why do you need the hyperbole in "IPv6 adoption will be a 
multifacted undertaking that will touch everyone in the organization 
unlike almost any other project."? How does the "unlike almost any other 
project" help the reader?

In 2.4.1, please rephrase "pretty much like". Are there any differences 
in the use of IPSec dependent on the address family that are important 
to call out? If not, why doesn't this say "the same as in"?

Section 2.4.2: As written, this says Etc. is an attack. Please change 
the introduction to the list to say "for example" or "in particular" and 
remove the Etc. If the point was to cause the reader to think about 
attacks beyond these listed, say that explicitly.

The 6th paragraph of 2.6 states the problem is "how to get host DNS 
records updated." The text in the rest of the paragraph only addresses 
this by implication. It looks more like the general discussion of SLAAC 
vs DHCPv6 instead of straightforwardly noting that a DHCPv6 server can 
be made to update DNS records.

The reference to RFC6866 in paragraph 7 of section 2.6 is unclear - what 
was it trying to point out?  I think the last sentence was trying to say 
'static address assignment (even if achieved with DHCP) is usually used' 
where it currently says 'SLAAC is rarely used'?

Section 3: The second paragraph doesn't add anything to the document.

Section 3.1 paragraph 2: I don't understand why the paragraph ends with 
"which is an important consideration". Can you delete the phrase without 
losing the message? If not, say why an enterprise would care whether or 
not _other_ enterprises had already deployed using BGP on their own.

Section 3.1 paragraph 4 : "will prefer to use" is out of place. Perhaps 
this should be stated as "will likely get better results using"?

Section 3.1 paragraph 5: Can you add a reference to a discussion of how 
keeping the MTU congruent simplifies operations?

In section 3.2 consider using the names from 4890 in the list ('Packet 
Too Big' rather than 'Unreachable packet-to-big')

Please check whether the sentence "To be fully compliant with [RFC5095], 
all packets containing the routing extension header type 0 must be 
dropped." is perhaps too simple a description of 5095? Does context keep 
you out of the "Segments left is zero" branch of that RFCs requirement?

In section 3.4, please remove "this may seem too time-consuming and too 
risky" or restate it with details. How is this observation supposed to 
help the reader?

In section 4.1 paragraph 3 "But the major issue is probably linked to 
all threats" would read better as "One major issue is threats"

In section 5 paragraph 3, please provide a reference to where these 
significant implications are discussed, or add some discussion. 
(Otherwise, what is the reader supposed to do with this observation?)

---

From: Jari Arkko <[email-masked]>
Date: Thu, 26 Jun 2014 16:08:36 +0100

Thank you Robert for your (once again) in-depth review. But I have a question - was there a response to the comments? My e-mail system does not show one, but maybe I missed it.

Jari

On 05 Jun 2014, at 20:00, Robert Sparks <[email-masked]> wrote:

> Summary: This draft is basically ready for publication as an Informational RFC,
> Overall, the list of issues to consider, and the compendium of references is very useful, but there are large stretches of text that really aren't helping the reader, and they make the good stuff harder to see.
> 
> I encourage the group to take one more editorial pass, focusing on removing as much text as possible without losing the message.
> 
> Please help the IESG and the RFC-Editor out: the shepherd's writeup should say something about why deviating from the style guide's restriction on number of authors is is appropriate for this document.
> 
> The first paragraph of section 1.3 starts talking about phases as if they've already been described. As written, it says that beginning with the External Phase is recommended in RFC5211. But the words "External Phase" do not appear in 5211, and its not clear on a quick read exactly what in 5211 you were hoping to point out here.  Please introduce the phases before this point, and change the callout to 5211 to make it more clear how what 5211 is saying ties into this document.
> 
> Why is "Other Phases" capitalized in 2.1? The number of phases defined in this document is small - I suspect this text is older and left room for the group to decide to define more phases. Consider just listing what you ended up with explicitly.
> 
> Section 2.1 contains sentences like "The project manager will need to spend some time on planning." That is obvious, and you've already established that planning needs to happen. This paragraph (perhaps much of this section) would be improved by removing as much text as you can. It already speaks mostly in terms of the benefits of planning. Making that a more explicit goal in the writing structure would help identify what can be taken away without losing the message. Overall, trying to describe what good project management entails is a bit out of place. Perhaps you should just say "This requires good project management skills"?
> 
> In 2.2.2 you say "Applications should be made to use APIs". That seems an odd construct for an IETF document. Perhaps you could observe, rather than command, here? Would saying something like "Applications that use APIs to hide the specifics ... will be easier to take through the migration" make the point?
> 
> In 2.3, why do you need the hyperbole in "IPv6 adoption will be a multifacted undertaking that will touch everyone in the organization unlike almost any other project."? How does the "unlike almost any other project" help the reader?
> 
> In 2.4.1, please rephrase "pretty much like". Are there any differences in the use of IPSec dependent on the address family that are important to call out? If not, why doesn't this say "the same as in"?
> 
> Section 2.4.2: As written, this says Etc. is an attack. Please change the introduction to the list to say "for example" or "in particular" and remove the Etc. If the point was to cause the reader to think about attacks beyond these listed, say that explicitly.
> 
> The 6th paragraph of 2.6 states the problem is "how to get host DNS records updated." The text in the rest of the paragraph only addresses this by implication. It looks more like the general discussion of SLAAC vs DHCPv6 instead of straightforwardly noting that a DHCPv6 server can be made to update DNS records.
> 
> The reference to RFC6866 in paragraph 7 of section 2.6 is unclear - what was it trying to point out?  I think the last sentence was trying to say 'static address assignment (even if achieved with DHCP) is usually used' where it currently says 'SLAAC is rarely used'?
> 
> Section 3.1 paragraph 2: I don't understand why the paragraph ends with "which is an important consideration". Can you delete the phrase without losing the message? If not, say why an enterprise would care whether or not _other_ enterprises had already deployed using BGP on their own.
> 
> Section 3.1 paragraph 4 : "will prefer to use" is out of place. Perhaps this should be stated as "will likely get better results using"?
> 
> Section 3.1 paragraph 5: Can you add a reference to a discussion of how keeping the MTU congruent simplifies operations?
> 
> In section 3.2 consider using the names from 4890 in the list ('Packet Too Big' rather than 'Unreachable packet-to-big')
> 
> Please check whether the sentence "To be fully compliant with [RFC5095], all packets containing the routing extension header type 0 must be dropped." is perhaps too simple a description of 5095? Does context keep you out of the "Segments left is zero" branch of that RFCs requirement?
> 
> In section 3.4, please remove "this may seem too time-consuming and too risky" or restate it with details. How is this observation supposed to help the reader?
> 
> In section 4.1 paragraph 3 "But the major issue is probably linked to all threats" would read better as "One major issue is threats"
> 
> In section 5 paragraph 3, please provide a reference to where these significant implications are discussed, or add some discussion. (Otherwise, what is the reader supposed to do with this observation?)
> 
> 
> 
> 
> _______________________________________________
> v6ops mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/v6ops

---

From: Robert Sparks <[email-masked]>
Date: Thu, 26 Jun 2014 10:22:34 -0500

No, I don't think I've seen a response.

RjS