RE: IPS WG Last Call: Structural Improvements

[Brian Forbes <bforbes@Brocade.COM>]

First, let me say that the document continues to improve, and I think the
technical issues are winding down.  Julian deserves our appreciation for
having shown so much patience and attention to detail.

In the past I've suggested in private discussions that the document has
significant readability and/or structural challenges.  One of the esteemed
WG co-chairs has challenged me to be more specific.  

To be more specific & constructive, and to see whether there is support from
others for these suggestions, here goes:

- 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.

-  There should be many more cross-references in a document this size.

- 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 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.

- Several sections are quite long and contain multiple topics.  Ideally, any
section longer than a page or two should be broken up, especially if there
is no other relief such as tables, bullets, or diagrams.  (Julian has
recently done this in 2.4)  

IMHO the single biggest improvement would be a tutorial introduction to
Section 4 that starts with the most basic concepts and terminology.

Brian Forbes
Brocade Communications 
-----Original Message-----
From: Julian Satran [mailto:Julian_Satran@il.ibm.com]
Sent: Monday, August 12, 2002 8:05 AM
To: ips@ece.cmu.edu
Subject: IPS-ALL: IPS WG Last Call on the iSCSI draft -- ends Sunday, Augu
st 25th



Dear All, 

As for the first WG Last Call you will find at: 

http://www.haifa.il.ibm.com/satran/ips 

A list of issues and their resolution and the "running version 16" in pdf
and text. 

Julo 
----- Forwarded by Julian Satran/Haifa/IBM on 08/12/2002 08:49 AM ----- 
Elizabeth Rodriguez <erodrigu@Brocade.COM> 
Sent by: owner-ips@ece.cmu.edu 
08/12/2002 12:01 AM 
        
        To:        "'ips@ece.cmu.edu'" <ips@ece.cmu.edu> 
        cc:         
        Subject:        IPS-ALL: IPS WG Last Call on the iSCSI draft -- ends
Sunday, Augu        st 25th 

       


All,

We would like to announce IPS WG last call on the iSCSI draft.
This is the second WG last call, and all comments from the first WG last
call period should be addressed by this draft.
(Note:  Addressed means that all comments were considered, not necessarily
accepted.)

The last call period is for two weeks, ending at 5pm EST on Sunday, August
25th.
Editorial comments may be directly sent to Julian Satran
(Julian_Satran@il.ibm.com), with copy to myself (erodrigu@brocade.com),
David Black (black_david@emc.com) and John Hufferd (hufferd@us.ibm.com).
Technical comments should be sent to the IPS mailing list for discussion.

There are two versions of the document available:
Text:  http://www.ietf.org/internet-drafts/draft-ietf-ips-iscsi-15.txt 
PDF:  http://www.ietf.org/internet-drafts/draft-ietf-ips-iscsi-15.pdf

The two documents should be identical, but the official version is the text
version.

Thanks,

Elizabeth Rodriguez & David Black,
IPS co-chairs