Feedback on the MSS draft - document layout issues

[Steve Hole <steve.hole@messagingdirect.com>]

1.  You will have to be careful about markup for IETF standards track.
    Specifically there are some rules regarding use of graphics and use
    of bold/italics/underline.   You should go to the IETF web pages and
    look at the rules for IETF draft submission.   It will explain
    everything that you need to know.

    And yes, I do agree that the representation is a bit archaic, but
    that's not really the point.   Document format is not the hill to
    die on when trying to get something on the standards track.   Those
    are best fought when it is someone else's document that will get
    held up in process :-)

2.  Recommend splitting Section 4.1 into two sections:

    4.1 Summary of Contents
    4.2 Document Conventions

3.  Recommend that the sections in 5.1 that deal with "what this
    document contains" should be moved to section 4.1.

4.  Recommend that the remaining "Design Objectives" section be moved as
    first subsection of System Overview.

5.  The System Overview section is arguably one of the most important
    sections in the whole document, but (sorry) it really says nothing.
    Motherhood statements will only fly in the first paragraph of a top
    level section.  If it is this way simply because the document is
    early on, then that's fine.  If this was thought to be complete,
    then I would disagree and add a lot of content (in no particular
    order):

    - Definition of roles in the messaging system.
    - Definition of terms like "payload", "sender", "receiver",
      "transport" etc.
    - Definition of data flows through the system.
    - Definition of *location* of interfaces.
    - Definition of interaction with other ebXML components
    - Example usage scenarios (intranet, extranet)
    - Itemization of requirements (should be in the Design Objectives
      probably). 
    - A graphical system model/diagram.

6.  I see very little about transport bindings in the "specification"
    part of this document although there are some decent examples.
    Recommend that a Transport Binding section be added after the "ebXML
    Header Document" section that defines the semantics of using an
    ebXML MIME object on that transport.   Appendix E appears to be the
    location for this, and I would suggest that it be a main body
    section in its own right.

7.  Section 7 "Definition and Scope" is mis-titled.  I would suggest
    "ebxml Packaging - Envelopes and Containers" or something like that
    -- something that reflects what is actually being defined.  This
    SHOULD correlate to what the Design Objectives says the document
    defines.

8.  When making normative references to standardized MIME headers and
    the MIME spec, resist the temptation to re-specify the function of
    the header.   The normative reference is enough.   If you get it
    wrong, then you have conflict between this specification and MIME
    and that will not be good.   Just call the MIME subroutine.

    Specifically, remove the sections on the "boundary" attribute.
    Define only the headers and parameters that are specific to
    ebXML and that it will be the normative reference for.

    You can and should say "all mandatory headers as defined by [MIME]
    as well as the following ...".    Examples can show the complete
    set. 

9.  The terminology for Envelope, Container and Body Part is used
    inconsistently.   Based on my experience with other MIME multipart
    bindings, this really messes implementors up.   I personally like
    the term Container -- it has less baggage than Envelope.   It is
    easy to bind specific MIME message parts to a container object in
    your format model.   I can contribute some text here if you like.
    Not today though, I'm busy being a critic today.

10.  The ebXML participants should be relegated to an appendix.
     Interesting, but probably only to the participants.

11.  Appendix C is interesting and useful, but probably should be
     relegated to a separate historical document.  I think that it is
     important to document, but shouldn't clutter up a technical
     specification for implementors.  In the IETF, "model documents" or
     informational RFC's are often used for this purpose.

12.  It seems to me that some of the Appendix D stuff goes directly to
     requirements and may be a candidate for the system overview
     section.   It is certainly relevant to usage scenarios.

     The parts of Appendix D that discuss the history and how the
     decision was reached should also be relegated to an external
     document rather than be retained here.



---
Steve Hole
Messaging Direct
Mailto:Steve.Hole@MessagingDirect.com
Phone: 780-424-4922