Re: iSCSI: Brocade Editorial Comments on v14

["Julian Satran" <Julian_Satran@il.ibm.com>]

Brian,

Thanks again. I am getting (finally) through some of your editorials.
I am tempted to change in 4 responder/response to acceptor/acceptance.

How does it sound?

Julo

Brian Forbes <bforbes@brocade.com> 07/07/2002 09:35 PM Please respond to Brian Forbes

To:        Julian Satran/Haifa/IBM@IBMIL         cc:                 Subject:        iSCSI: Brocade Editorial Comments on v14

Attached is a list of comments on iSCSI version 14.  Although they include
some certifiable nits, I've tried to focus on things that might keep the
reader from understanding the material on the first pass.

Pulling the document together remains a Herculean effort; I'm thankful not
to be the editor at this point!  It requires not only terrific attention to
detail, but a great deal of patience and pursuasiveness to get convergence
to a final product.

Having said that, I'll proceed to test that patience and risk the editor's
wrath by listing things I think keep the document from being even more
readable:

.        The topic of login needs an overview section that introduces
concepts such as session phases, connection phases, session types,
declarations vs. negotiations, and login stages.  Much of the terminology is
introduced on the fly.  More precise and suggestive wording could be used
for key exchanges, e.g. 'offer' instead of 'use' or 'receive', and a
specific term for the answer to an offer should be defined and used
('selection'?).  The terminology of Request and Response continually gets in
the way of key exchanges, which can be originated by either end; perhaps an
inclusive term such as 'Message' could be used to refer to whichever of the
Request/Response duo is appropriate.

.        There is a great deal of repetition throughout the document, which
impacts maintainability as much as readability.  For example, the rules for
the length of unsolicited data with and without immediate data are covered
in several places.  As another example, t he fact that 0xffffffff is
reserved for TTT is mentioned several times.  As a third example, the rules
for setting TSIH, etc. to accomplish various flavors of connection/session
(re)establishment are covered in multiple places.  In the early sections of
the document, these are gratuitous details and can be omitted entirely.  In
intermediate sections, such details are better handled by forward reference
to a (single) section where they are defined once.

.        As a related observation, there should be many more cross-references
in a document this size.

.        There is also repetition of normative text, with the same suggested
fixes.  I think we all agree that each normative should ideally occur only
once.

.        For readability, any comma-separated list of more than 2 or 3 items
should be expressed as a list of bullets instead.  Examples abound in the
state diagrams.

.        There are many cases where an English phrase is used as a euphemism
for well-defined iSCSI term.  One example is the use of a phrase like 'the
maximum length of unsolicited data negotiated during login' instead of
'FirstBurstLength'.  Such euphemisms might be justified early in an
overview, before the iSCSI term has been introduced, but anywhere else it
leaves the reader wondering.  At a minimum, euphemisms should be
supplemented by appending the iSCSI term in parentheses, and in many cases a
forward section reference is also in order.  It also suggests that more
iSCSI terms should be introduced (but not necessarily defined in detail)
earlier in the text; e.g. frequently-mentioned key names.

.        There are several examples of gratuitous terminology.  Example:  the
term 'task failover' is used a couple of times but the majority of text
talks about 'connectiono allegiance'.  Example:  the term 'decommissioning'
is used for vis-a-vis connections, but only 3 times.

.        There seem to be cases where new terminology/notation would be very
useful.  There are many phrases of the form 'an X having the Y bit set to
1'; when multiples of these appear in the same sentence-and they do- parsing
becomes difficult.  One could define a flavor of X that implies having the Y
bit set; e.g. one could define a 'final Data-out PDU' as a PDU having the F
bit set.  Another example: one could define a 'completed sequence' as a
sequence of PDUs where the last or only PDU has the F bit set'.

.        Several sections are quite long and contain multiple topics, e.g.
section 2.2.4.  Ideally, any section longer than a page should be broken up,
especially if there is no other relief such as tables, bullets, or diagrams.


I don't expect to see many of these addressed immediately, but hope they
might be kept in mind if there is ever a lull in the proceedings.

Regards,


Brian Forbes
Technology
Brocade Communications




#### mime001.txt has been deleted (was saved in repository My Attachments Repository ->Link) from this note on 09 July 2002 by Julian Satran