iSCSI: editorial rewrite not needed

[Black_David@emc.com]

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
black_david@emc.com       Mobile: +1 (978) 394-7754
---------------------------------------------------