Re: [sca-bindings] Review of sca-binding-ws-spec-cd02-rev3.pdf

[Mike Edwards <mike_edwards@uk.ibm.com>]

Folks,

Some comments inline...

Yours,  Mike.

Strategist - Emerging Technologies, SCA & SDO.
Co Chair OASIS SCA Assembly TC.
IBM Hursley Park, Mail Point 146, Winchester, SO21 2JN, Great Britain.
Phone & FAX: +44-1962-818014    Mobile: +44-7802-467431  
Email:  mike_edwards@uk.ibm.com

From:	Eric Johnson <eric@tibco.com>
To:	OASIS Bindings <sca-bindings@lists.oasis-open.org>
Date:	17/06/2009 18:33
Subject:	[sca-bindings] Review of sca-binding-ws-spec-cd02-rev3.pdf

---

As I'm trying to read through these documents, I find
the highlighting of the normative statements is actually quite annoying. 
It makes it much harder to read the document.  In addition, I had
to force my PDF viewer to no color, because the default "highlight"
color with my windowing theme exactly matches the highlight color chosen
for the document, and searching for a result in a normative statement would
then not show where the search result was found.  My suggestion would
be to change the color of the normative text itself to a gray just shy
of black, rather than changing the background color of the text.

<mje>I'm probably biased, since this
form of marking was started by me.  However, I think that background
highlighting is essential - merely changing the font colour is ineffective
to the point of uselessness.  We can debate the highlight colour -
if this bright yellow is too painful for the eyes, we can choose a more
subdued colour.</mje>

Also seems to me that the normative numbering declarations could be superscripted,
so that it is easier to read the text and let my eyes skip over the reference
numbering.
<mje>This I simply don't agree with.
It's fine as it is, in my opinion.</mje>
Those are just my personal preferences, though.

Line 101-103 - sentence is repeated.

Line 207: "WSDL 1.1 message parts can point to an XML Schema element
declaration or an XML Schema type."  Mismatched parallelism. 
Ought to be "... can point either to an XML Schema element
declaration or to an XML Schema type declaration."

Line 219: "Port" --> "port"

Line 265 - 266: "SCA runtime implementations MAY provide additional
metadata that is associated with a web service binding."  Unfortunately,
this sentence seems so out of context to me, that it is difficult to figure
out what it was actually referring to.  Are we talking here about
providing additional metadata in the generated WSDL document?  That
would push section 2.5 to be section 2.4.1.  However, I think what
we really mean here is that we really mean that an SCA binding.ws element
might contain additional metadata to help configure non-SCA aspects of
a web-services binding.  However, that's not a normative constraint
on the runtime, so then I don't get the normative statement.

I think I need to raise an issue for the above.  Am I missing something?
<mje>No, you're not missing anything.
 This is a normative statement too far.  It is simply redundant
and unecessary.  The schema definition says everything normative here.
I'd change the MAY to a "can" and
reduce this to a simple factual statement.</mje>

Line 306: "... web service binding is configured with a policy intent(s)
..." --> "... web service binding is configured with any
policy intent ...
+1
Should we swap sections 3 & 4, especially since section 3 makes reference
to details specified by section 4?
+1
Line 443-444: Parallelism again: "MUST follow either the rpc-literal
or document-literal pattern." --> "MUST follow either the
rpc-literal pattern or the document-literal pattern."

Line 461: "of “Simple Object Access Protocol (SOAP) 1.1” [SOAP11]
" --> This is an inconsistent reference.  So far as I've discovered,
we don't inline the titles of the target of the reference elsewhere, so
this should change to just "of [SOAP11]".
<mje>On this point, I have the opposite
point of view.  I prefer to spell out the name of the target document
in all these locations.  The [xxxx] tag is intended to be a reference
link to the place at the top of the document where the location of that
referenced document is actually held.  It isn't meant to be a readable
part of the document text. </mje>
Thankfully, all but one of the above are editorial...

-Eric.

---------------------------------------------------------------------
To unsubscribe from this mail list, you must leave the OASIS TC that generates
this mail. Follow this link to all your TCs in OASIS at: https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php

---

Unless stated otherwise above:
IBM United Kingdom Limited - Registered in England and Wales with number 741598.
Registered office: PO Box 41, North Harbour, Portsmouth, Hampshire PO6 3AU