SORT BY:

LIST ORDER
THREAD
AUTHOR
SUBJECT


SEARCH

IPS HOME


    [Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

    Re: iSCSI: Brocade Editorial Comments on v14




    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



Home

Last updated: Tue Jul 30 10:39:13 2002
11481 messages in chronological order