Subject: RE: iSCSI: editorial rewrite not needed

From: "Julian Satran" <[email-masked]>
Date: Thu, 11 Jul 2002 17:42:49 +0300

David,

I don't want to spend time o n the agenda either. I hope however that you 
might want to set you priorities 
to include work in this group.
The complaints where not only about the lateness of the comments but  also 
about their classification.

Julo

[email-masked]
07/11/2002 07:35 AM
Please respond to Black_David

        To:     Julian Satran/Haifa/IBM@IBMIL
        cc:     [email-masked]
        Subject:        RE: iSCSI: editorial rewrite not needed

Julian, 

This complaining about lateness of comments really needs to stop.
WG Last Call is about gathering up any and all comments on the
spec, and the timing of comments is whatever happens.  I would
have liked to have been able to get my comments in much earlier
also, but life is what happens while one is busy making other plans ...

As for the overview sections for both error recovery and login -
it is still my view that both the Current Sections 4 and 6 need them
(if there's text that can be moved down from Section 2 to help accomplish
this for error recovery, that's fine).  The fact that the structural
issues in these sections that make them hard to understand may have been
there for a long time is not a good reason to avoid correcting them.

I'd really rather not have to spend Yokohama agenda time on editorial
issues like these, but if you insist ...

Thanks,
--David

> -----Original Message-----
> From: Julian Satran [mailto:[email-masked]]
> Sent: Wednesday, July 10, 2002 12:00 AM
> To: [email-masked]
> Cc: [email-masked]; John Hufferd; [email-masked]
> Subject: Re: iSCSI: editorial rewrite not needed
> 
> 
> 
> David,
> 
> Swapping 5 and 6 is not a major issue. However I have to object to the
> recovery overview.
> It is already contained in 6 itself and in 2.
> 
> And I have to stand by John's comment about the lateness of 
> your comments.
> It is disappointing that you got to this that late - and most of your
> comments refer to text that was there
> for a long time.
> 
> Julo
> 
> 
> 
> 
> 
> 
> 
>                       [email-masked] 
> 
> 
>                       om                       To:       John 
> Hufferd/San Jose/IBM@IBMUS 
> 
>                       Sent by:                 cc: 
> [email-masked] 
> 
>                       [email-masked]        Subject: 
> iSCSI: editorial rewrite not needed 
> 
>                       .edu 
> 
> 
> 
> 
> 
> 
> 
> 
>                       07/09/2002 09:44 
> 
> 
>                       AM 
> 
> 
>                       Please respond to 
> 
> 
>                       Black_David 
> 
> 
> 
> 
> 
> 
> 
> 
> 
> 
> 
> John,
> 
> My original text was:
> 
> Global Editorial comment: Both the login (4) and error handling (6)
> sections
> feel like one of those old Adventure mazes of twisty little 
> passages - all
> the
> details seem to be there, for the most part they're correct, 
> but it's very
> hard
> to get the proverbial "big picture" of how everything fits 
> together, in
> terms
> of how the various mechanisms work with each other and how 
> they accomplish
> the overall functionality.  Both of these could use overview sections
> describing
> how the functionality breaks down into the pieces described in the
> subsections
> and how they fit together.  Swapping the order of Sections 5 
> and 6 would
> also
> be a good idea so that the discussion of Error Handling and 
> Recovery comes
> before the state machine descriptions that contain a lot of 
> the details of
> how errors are handled.  For error handling, moving Section 
> 6.13 to the
> front of Section 6 would help organize the Section better, 
> and care should
> be
> taken to define or replace terms like "restart login" and 
> "recovery R2T"
> that are currently used without definitions.
> 
> > I disagree with the editorial rewrite, especially at this 
> late state.  If
> > they were important that should have been brought up earlier.
> 
> I fail to see how you got from my original text whose primary 
> request was
> for "overview sections describing ..." to "editorial 
> rewrite", so I think
> you're seriously over-reacting.  Concerns about comprehensibility have
> been brought up on the list in the past.
> 
> > We should
> > not be discussing editorial style, but whether we have correctly
> specified
> > the protocol.
> 
> This isn't about "editorial style", but rather whether the 
> specification
> is comprehensible to an implementer who picks it up from 
> scratch without
> the benefit of this group's email discussions, short term memory, etc.
> 
> > We have already changed it a couple of times, and you are
> > now wanting it changed again.  This is a very big spec, and 
> each time we
> > make changes to pretty up the document, the more that is needed, and
> > someone else has another preference.
> 
> If the spec has problems, Working Group Last Call is the point in
> time to find and fix them, and if that takes serious effort, 
> c'est la vie.
> I'm prepared to listen to arguments that the spec is sufficiently
> comprehensible as to need no editorial changes, but I'm not 
> inclined to
> assign them a great deal of credibility at this juncture.
> 
> > It is already better then most of the
> > other IETF specs.  I think this causes a needless delay.
> 
> I disagree and take exception to the view that iSCSI
> is needlessly being held to a higher standard.  The need for a
> comprehensible spec is real, and that is not a higher standard
> than other IETF specs are generally held to, although there are
> some that have gotten away - IKE/ISAKMP and the related keying
> portions of IPsec are an example that we are unfortunately
> familiar with.  It should not take an iSCSI guru with a secret
> decoder ring to unscramble how the protocol works even if all
> the interacting pieces are correctly specified somewhere in the
> document.
> 
> On further reflection, I think that an overview section on error
> handling in the current Section 6 plus swapping the order of Section 5
> and Section 6 probably removes the need to tease apart the initiator
> and target state machine specifications in the current Section 5
> (my comments E.80 and E.81).  That should reduce the amount of work
> required provided that the overview text for error handling is well-
> written.
> 
> Thanks,
> --David
> ---------------------------------------------------
> David L. Black, Senior Technologist
> EMC Corporation, 42 South St., Hopkinton, MA  01748
> +1 (508) 249-6449            FAX: +1 (508) 497-8018
> [email-masked]       Mobile: +1 (978) 394-7754
> ---------------------------------------------------
> 
> 
> 
>

---

From: Bill Studenmund <[email-masked]>
Date: Thu, 11 Jul 2002 16:39:16 -0700 (PDT)

Julian,

I fail to understand your concern about lateness. This is last call. When
else should complaints come up? *After* last call???

Many of the things David was asking for are things that really should come
up about now, IMHO. Writing summaries & overviews when the material being
summarized is still in flux does not seem like a productive exersize.

As to their need, I think these changes (swapping sections 5 & 6, and
adding summaries) are needed. I think the current draft we have is not
intuitive for new readers. I know I've had a hard time figuring everything
out over the past four months. I think you do have everything in there,
it's just things aren't necessarily where new readers will expect to find
them.

Take care,

Bill