Comments on Public Review Draft Reference Architecture Foundationfor SOA CD02

[William Cox <wtcox@CoxSoftwareArchitects.com>]

Comments indicate (starting) line number, page, figure, or "general", followed by the comment.

I'm sending these comments as a member of the OASIS Technical Advisory Board.

bill cox

General   The document does not make clear how one would use the specification; the referenced joint white paper does not mention this specification. I would suggest a white paper (or an update to the referenced joint OMG/TOG/OASIS white paper) to make this clear. I have found ways to apply the information but guidance would make the specification more valuable.

General   The capitalization of sections is not consistent. Compare, e.g., 1.1.4 and 1.4.1.

General   Some of the diagrams seem very fuzzy. And if they were produced by a tool, the tool should be noted.

General   Semicolons appear to be frequently used where commas are more appropriate. Some specific examples are noted. (see also line 216)

General   The large number of emboldened terms defined and used is confusing;a separate (non-normative) glossary and index would make the document more useful.

General   Capitalization is not consistent between the normative and non-normative references and their use in the document. Needs general editorial correction.

General   A "typographical conventions" note under section 1.5 would make the document more useful and readable. Lee comments for line 314.

General   Many sections that should start on an odd page boundary do so only by accident. E.g. p24 as the start of a major section, the table of contents on page 4. This is difficult to read when printed double-sided.

Figure 24   The label should be reworded, perhaps to "Model Elements Described in Realizing a Service Oriented Architecture View" (eliminate "the" before "Realizing")

Line 35 p9   change semicolon after "owned" to a comma.

Line 67 p10   semicolon should be a comma.

Line 73 p10   It seems out of place to refer to ESBs as "emerging". Delete the word.

Line 91 p11    Are "technical products" the specifications described in [SOA-NAV]?

Line 92 p11   ".. where they plan to head on their SOA journeys" does not read well. "...their engagement with SOA technologies"?

Line 107 p11   "considerations for cross ownership boundaries" should perhaps read "consideration for reaching across ownership boundaries."

Line 132 p12   "positioning" (also on line 98) is jarring, and not what should be meant. Perhaps "descriptions"? "this specification"? "this work"?

Lines 147-152 page 12-13   The use of "system" is not clear. Many places where one would apply this work, e.g. in the Smart Power Grid, are actually "systems of systems." Are you ignoring that application? The wording on line 142 seems to suggest that "simple decomposition" is often not appropriate.  The analysis of the Smart Power Grid and service-oriented energy (references on request) requires information hiding and focus on the interaction across domains. Line 153 makes a clear statement, but this entire section could be better focused to make the statements more clear and better supported. The key points at the end are good. But the relationship between an ecosystem, "a system", and "participants" seems to indicate different levels of modeling, and a confusing approach. Finally, lines 157-159 are making a very important point that should be earlier in the section.

Line 158 p13   What does "peer-like" mean?

Lines 260-265 p15   I found this paragraph very confusing.  A bullet list might be more clear. The semicolons, solon, and the long items contribute to the confusion. The approach is good; the exposition here is weak.

Line 314 p17   "regular concepts" -- and "formally defined concepts". This is very muddled. The formally defined concepts may be defined elsewhere (the references for terminology are weak, or they're all defined in this spec). But many apparently formally defined concepts are used with bold, not capital letters (e.g. line 715, "joint actions"). The general typographical conventions should be listed in a following H3 subsection. The use of bold is not described, and can only be intuited from the text.

Line 373 p18   (also General): there are referenced, e.g. to Dublin Core Metadata Initiative and ISO 11179 (from Line 1859) that are not in the references. Include them, and verify others--some have missing references.

Line 386 and all of page 19   Is there a refernce for Critical Success Factors and "Critical Factors Analysis? Include one. Note that you use CFA as an abbreviation, but repeated indicate abbreviations for other terms in the doc -- refs if I have time.

Line 400 p20   Social effect is a forward reference. is it a formally defined concept/term? or a "regular concept" or term?

Lines 393ff p20   The goals are very abstract; the modeling is somewhat obscure (but I liked it eventually).  There are more forward reference; the definition of Critical Success Factors on Line 417 follows its first use on 377. Please pay attention to forward references--they're jarring and make the document less accessible. YOU know what they mean, the reader does not.

Line 457 p21   The definition of Trust (if this is a definition) should have the relationship to common security models explained clearly.

Line 465 p21   This is well stated.

Line 478 p21   The "key tenets" GUIDED the evolution, not "guide". Presumably this occured in the past.

Line 480-541 p22-23   These principles are very important, and generally clearly described and defined. It's all the more jarring when the occasional lapses are noted.  (BTW, this is a compliment!)

Line 500 p22   This implication is confusing; reword it with less complex sentences. The implications are ones with which I agree, but a reference or more clear writing would support them better.

Line 527 p22   "fortunately" doesn't seem in the correct tone. Delete it and the comma following.

Line 578 p24   "the Acting"... this sentence is confusing. If "ecosystem" were capitalized it would be more clear that this is a defined phrase--otherwise one asks What is "the Acting"? The use in line 580 is more clear because of capitalization.

Line 586 p25   "acting against services" sounds strange. Is there better wording possible here?

Line 612 p26   The text on "actor" and the footnote indicate a great confusion. When are you using which term? Why are you using a term that conflicts with the standardized notation of your modeling tool? Please consider how this could be clarified. Section 3.2.1 didn't help much.

Line 657 p27   "this initial model..." what does "initial" mean? delete it.

Line 671 p27   "measurable state" -- I disagree. A measurable state or set of states would limit goal explosion in the discussion; an actor seeks to establish perhaps one or more conditions that are relevant, and ignores others that are not--hence a set of states (or a slice through the state space).

Line 685 p28   "measurable change" -- perhaps "detectable"? Either suggests that the measurement/detection need not occur, so it's quite abstract.

Line 693 p28   "In effect (sic)"... cute, but get rid of "(sic)". It should be used in quotes and in square brackets.

LIne 698 p28   The state change approach is perhaps harder to explain than a simpler finite automata model. I think more foundation for this fundamental concept is important.

Line 757 p29   "honor the fact" -- perhaps "more clearly understand the fact"?

Line 834 p32   This section seems to limit the use of the "service" which surely is a fundamental concept. While seemingly correct, the exposition is confusing.

Line 891 p33   How does the social structure model relate to services?

Line 943 p34   ownership boundaries is another forward reference. A glossary/index would be useful. Refs to Line 1241.

Line 1259 p44   Are all actors trusting? Or is this the subclass of actors who care about trust? The definition of Trust on 1249 seems very general, and not descriptive of the common use of trust in security models. I think this is deliberate, but it should be pointed out.

Line 1321 p46   It is unfortunate that this definition conflicts with WS-BusinessTransaction, an OASIS standard. Perhaps a footnote would be in order.

Line 1375 p48   This and similar figures are very hard to read.

Line 1384 p48   The callout of semantics is very late in this section.

Line 1453 p50   What do I do with this? What is its utility? Please explain in the text.

Line 1556 p53   From Joint Action to "exchange of messages". Which way to describe?

Line 1608 p55   Explain how these policies relate (or dont) to security and other WS policies.

Line 2206 p71   "Section x" See also line 3121 and 3598.

Line 2254 p72   Message exchange? why all of the joint action statements?

General: The "Architectural Implications" Sections are very useful.

Line 3488 p105   Why the box?

Line 3623 and section   I look forward to updated text in this section.

--
William Cox
Email: wtcox@CoxSoftwareArchitects.com
Web: http://www.CoxSoftwareArchitects.com
+1 862 485 3696 mobile
+1 908 277 3460 fax