Subject: RE: IPS WG Last Call: Structural Improvements

From: Brian Forbes <[email-masked]>
Date: Fri, 23 Aug 2002 17:56:25 -0700

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:[email-masked]]
Sent: Monday, August 12, 2002 8:05 AM
To: [email-masked]
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 <[email-masked]> 
Sent by: [email-masked] 
08/12/2002 12:01 AM 
        
        To:        "[email-masked]'" <[email-masked]> 
        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
([email-masked]), with copy to myself ([email-masked]),
David Black ([email-masked]) and John Hufferd ([email-masked]).
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

---

From: Luben Tuikov <[email-masked]>
Date: Mon, 26 Aug 2002 18:18:30 -0400

> negotiations, and login stages.  Much of the terminology is introduced on

Agreed.

While the details are there and explained, presenting the ``big picture''
of the procedure would be invaluable to the uninitiated reader.

Currently a new reader in encumbered with the task of building the ``big
picture'' by just reading about the details (CSG/NSG, etc.).

> earlier in the text; e.g. frequently-mentioned key names.

At this stage we can afford to get rid of euphemisms altogether. I.e.
there'd be no more changes of names at all.

If ``FirstBurstLength'' is intended, then that name should be used,
and if the reader needs to know what it is, they can always look up
its definition elsewhere in the iSCSI document.

This would make the text more robust and more clear (in my opinion).
 
> bit set; e.g. one could define a 'final Data-out PDU' as a PDU having the F

Agreed.

Defining ``final Data-x PDU'' to be equivalent to a PDU whose F bit = 1,
and then defining a sequence to end with a final Data-x PDU,
would clarify text in the sense that instead of saying:
``has to have it's F bit = 1'' one would say
``the PDU sequence'' and that's it.

If one wants to know what is meant, they'd look up ``PDU sequence'',
then ``final Data-x PDU'', etc. Clearly a structurally more sound
document.

-- 
Luben

P.S. Yes, indeed, semantics _do_ make a difference. And we've seen this
fact shown numerous times in the latter 20th century, contrary to
the mid-20th century fad ``It's only semantics''.