Re: Feedback on the MSS draft - document layout issues

[Christopher Ferris <chris.ferris@east.sun.com>]

Steve,

Again, thanks for the feedback. All points well taken. 

Chris

Steve Hole wrote:
> 
> 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

-- 
    _/_/_/_/ _/    _/ _/    _/ Christopher Ferris - Enterprise Architect
   _/       _/    _/ _/_/  _/  Phone: 781-442-3063 or x23063
  _/_/_/_/ _/    _/ _/ _/ _/   Email: chris.ferris@East.Sun.COM
       _/ _/    _/ _/  _/_/    Sun Microsystems,  Mailstop: UBUR03-313
_/_/_/_/  _/_/_/  _/    _/     1 Network Drive Burlington, MA 01803-0903