Subject: Re: [trill] RtgDir review: draft-ietf-trill-aa-multi-attach-03

From: Alia Atlas <[email-masked]>
Date: Mon, 27 Jul 2015 14:19:31 -0400

Michael,

Thanks very much for the review.

Regards,
Alia

On Sat, Jul 25, 2015 at 8:50 PM, Michael Richardson <[email-masked]>
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-trill-aa-multi-attach-03.txt
> Reviewer: Michael Richardson
> Review Date: 2015-07-25
> IETF LC End Date: N/A
> Intended Status: Proposed Standard
>
> Summary:
>
> This document is basically ready for publication, but could benefit from
> some simplication of language. The forest is often lost for the inline
> details of the trees.  The world would not end if it was published as is.
>
>
> Comments:
>
> Given that the introduction precedes the glossary, it is very TLA heavy.
> I wonder if the Introduction could be simplified, or if it is even
> necessary to say so much so precisely.
>
> Terms that stood out without definition: clumps.
> (I suspect that this is a TRILL core term)
>
> Minor Issues:
>
> I find that the english is rough in places, perhaps a some words or
> half sentences obvious to the authors is missing. e.g. last paragraph
> before section 4.  Sentences seem needlessly long.
>
> If I were implementing in an Agile setting, I'd be writing multiple user
> stories per sentence.  Consider the development manager trying to reconcile
> tickets back to parts of the document.
>
> I'd rather that more periods and more new paragraphs were used to explain
> things.  I don't consider this an english issue, rather an issue of
> too many nested ideas:
>          (A (and also B (except C (unless D))) then E)
>
> I think the document was started with the idea of trying to explain why
> Option C has been chosen by walking the reader through all the choices, and
> comparing them.  Yet, that actually isn't what is happening: the options
> are
> not well enough explained to understand the path not taken.  Either say
> less
> about options A and B, or say more.
>
> I found section 5 (meeting design goals), while dense, to be very well
> written and presented. Kudos.
>
> No major issues found.
>
>
>
> --
> Michael Richardson <[email-masked]>, Sandelman Software Works
>  -= IPv6 IoT consulting =-
>
>
>
>

---

From: Mingui Zhang <[email-masked]>
Date: Wed, 29 Jul 2015 01:26:16 +0000

Hi Michael,

We really appreciate you review! 

I will reshape the introduction to make it simple. The issues being pointed out are fair. I think I can address them with a new version.

Thanks,
Mingui

> -----Original Message-----
> From: Michael Richardson [mailto:[email-masked]]
> Sent: Sunday, July 26, 2015 8:51 AM
> To: =?utf-8?Q?=E2=80=8Brtg-ads?=@tools.ietf.org;
> [email-masked]; [email-masked]
> Subject: RtgDir review: draft-ietf-trill-aa-multi-attach-03
> 
> 
> 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.
> 
> This document is basically ready for publication, but could benefit from some
> simplication of language. The forest is often lost for the inline details of the
> trees.  The world would not end if it was published as is.
> 
> 
> Comments:
> 
> I wonder if the Introduction could be simplified, or if it is even necessary to say
> so much so precisely.
> 
> I find that the english is rough in places, perhaps a some words or half
> sentences obvious to the authors is missing. e.g. last paragraph before section
> 4.  Sentences seem needlessly long.
> 
> If I were implementing in an Agile setting, I'd be writing multiple user stories
> per sentence.  Consider the development manager trying to reconcile tickets
> back to parts of the document.
> 
> things.  I don't consider this an english issue, rather an issue of too many
> nested ideas:
> I think the document was started with the idea of trying to explain why Option
> C has been chosen by walking the reader through all the choices, and
> comparing them.  Yet, that actually isn't what is happening: the options are
> not well enough explained to understand the path not taken.  Either say less
> I found section 5 (meeting design goals), while dense, to be very well written
> and presented. Kudos.
> 
> No major issues found.
> 
> 
> 
> --