Review-Feedback Sects. 1, 2, 3

[Rex Brooks <rex.brooks@ncoic.org>]

Hi Everyone,

Here are my brief feedback/review comments against for Sects 1, 2, 3 of the RAF spec revision entitled “GOLD STANDARD - 2011-04-30”.  Following Jeff’s lead, I provide the comments and let you or Peter handle the integration of the updates from mine and everybody else’s from the subcommittee for this two week review period. I have also attached my review as Word .doc file for convenience. Please excuse the entries where I neglected to color code the specific suggested changes.

Cheers,
Rex

Line 353, Sect. 2.1

I would prefer the term “requirements-capture” be hyphenated for clarity as a compound term rather than ‘requirements’ modifying ‘capture’, which can be confusing.

Lines 364-366 Suggest:

The key factors that govern effectiveness from a participant’s perspective are actions undertaken– especially across ownership boundaries – with other participants in the ecosystem which lead to measurable results.

Rather than

The key factors that govern effectiveness from a participant’s perspective are actions undertaken– especially across ownership boundaries – with other participants in the ecosystem and lead to measurable results.

Either way, the grammar needs to be corrected.

Note: I’m particularly happy with Section 2. It manages to embody the principles it espouses.

Line 523, Sect. 3 Suggest:

… particular needs of each participant.

Rather than:

… particular needs of each person.

Note: This is preference only. It just feels more in keeping with “participation in a SOA Ecosystem.” Also, needs may be held by a group or software delegate.

Line 562, Sect. 3. Suggest:

… or delegates who act only on behalf of participants (without themselves having any stake in the actions they have been tasked to perform)

Rather than:

… or delegates who act only on behalf of participants (without themselves having any stake in the ecosystem)

Note: Delegates can’t act within a system without having a stake in it as peformers if nothing else.

Line 624, Sect. 3.1 space needed between ‘with’ and ‘no’ in:

A peer group is a social structure withno discernable leadership structure, that

Line 663-664, Sect. 3.1.1 Suggest:

ecosystem; or a delegate (a human actor with no stake in the action or an automated agent), acting on behalf of a participant

Rather than:

ecosystem; or a delegate (a human actor with no stake in the ecosystem or an automated agent), acting on behalf of a participant

Note: Same as above. If you work in the ecosystem, you have a stake in it.

Lines 693-694+, Sect 3.1.1 Suggest:

whether the delegation is of work procedures carried out by human agents who have no stake in the actions with which they are tasked, but act on behalf of a participant who does;

Rather than:

whether the delegation is of work procedures carried out by human agents who have no stake in the ecosystem but act on behalf of a participant who does;

Note: Same as above.

Line 709, Sect. 3.1.1 remove ‘s’ from perform in:

participant may performs

Line 747. Sect.3.1.2 Suggest:

opposed to permissions and obligations which are associated with actors

Rather than:

opposed to permissions and obligations which are associated with actions

Line 825 Sect. 3.1.3.1 Suggest:

example globally unique Internationalized Resource Identifiers (IRIs).

Rather than:

example globally unique IRIs.

Lines 823-836 Suggest breaking into shorter sentences. Reader fatigue sets in early here, unlike Section 2. Grammar is not wrong, just tedious.

Line 919, Sect 3.1.4 Reply to Peter’s comment that trust and risk are not symmetrical: True, but the divergence occurs in the process of assessing reputation and evidence. There could be significant differences shown in subsequent diagrams if we were to go into greater detail, especially with regard to risk mitigation and the whole briarpatch of insurance, which could be either a separate service or an augmentation within the service itself. However, I don’t think we want or need to go into that in this effort. It is out of scope now, but would make a good subject for further work.

Line 967, Sect. 3.1.4 change ‘constraint’ to ‘constrain in:

… does constraint how they act if and when action covered by the contract occurs (for

Line 969-970, Sect. 3.1.5 Either capitalize both or use lower case for both ‘permission’ and ‘Obligation’ in:

Two important types of constraint that are relevant to a SOA ecosystem are permission and Obligation

Line 972, Sect. 3.1.5 Suggest:

A permission is a constraint that identifies actions that an actor is (or is not) allowed to perform and/or the states the actor is (or is not) permitted.

Rather than:

A permission is a constraint that identifies actions that an actor is (or is not) allowed to perform and/or the states the actor is (or is not) permitted to be in.

Note: Definition of Permission is clumsy, ends with preposition.

Lines 974-978, Sect. 3.1.4 Please break into shorter sentences. Long sentences seem unnecessarily complex.

Lines 980-981, Sect. 3.1.5 Suggest:

An obligation is a constraint that prescribes the actions that an actor must (or must not) perform and/or the states the actor must (or must not) attain or maintain.

Rather than:

An obligation is a constraint that prescribes the actions that an actor must (or must not) perform and/or the states the actor must (or must not) be in

Note: Same as above wrt ending with a preposition. Just clumsy.

Lines 998-999 Sect. 3.1.6 Suggest:

A communication involves one or more actors performing the role of sender and at least one other actor performing the role of recipient

Rather than:

A communication involves one or more actors playing the role of sender and at least one other actor playing the role of recipient

Note: Playing implies frivolity which I think is inappropriate for this work..

Line 1056, Sect. 3.2 Suggest:

ownership domain; thus generating a need for which they seek and leverage services

Rather than:

ownership domain; thus generating a need for which they look for and leverage services

Lines 1065-1066, Sect. 3.2 Suggest:

The Action Model is basically a description of the actions that the service is willing to do on behalf of another. It should be associated with a real-world effect.

Rather than:

Action model is basically a description of the actions that the service is willing to do on behalf of another. They should be associated with a real-world effect.

Lines 1068-1069 Can’t make sense of:

model identifies the actions that the service consumer will have to be a party to in order to access or generate the real-world effect.

Please fix. Does this perhaps attempt to say:

model identifies the actions that the service to which the consumer will necessarily be a party in order to access or generate the real-world effect. ?

Note: I think that’s what is meant, but I have to puzzle over it to come to that conclusion. That’s too much work for the reader.

Line 1087, Sect. 3.2 Suggest:

All of these things are important to getting to the core of participants’ concern in a SOA

Rather than:

All of these things are important to getting to the core of participants’ interest in a SOA

Note: I think this is needed to maintain the viewpoint.

Lines 1096-1098, Sect. 3.2 Suggest:

In order to act in a way that is appropriate and consistent participants must communicate with each other about their own goals, objectives and policies, and those of others. This is the prime purpose of Semantic Engagement.

Rather than:

In order to act in a way that is appropriate and consistent both to their own goals, objectives and policies, and those of others, participants must also communicate with each other.

Note: Current language is a bit tortured.

Line 1102, Sect. 3.2 Please correct

Sections Error: Reference source not found6 and 3.1.7.

Lines 1115-1116, Sect. 3.2.1 Suggest deleting phrase: “or by itself” or replacing with “or inaccessible by potential service consumers”:

A capability that is isolated, or by itself (i.e., not accessible to potential consumers) is emphatically not a service

Note: Awkward.

Lines 1186-1187 Sect. 3.2.2 Suggest:

software details will be as brittle to change as the underlying code and will not exhibit the characteristic of loose coupling as discussed in the SOA-RM..

Rather than:

software details will be as brittle to change as the underlying code and will not exhibit the undefined but intuitive characteristic of loose coupling.

Line 1312 Sect 3.3.3 Suggest:

• Requiring policy conflict resolution techniques

Rather than:

• Policy conflict resolution techniques

Note: This is consistent with Line 1291

Lines 1320-1321, Sect.3.3.4 Suggest:

• Identifying the higher-level structure such as the illocutionary form of the communication; e.g. policy assertion, contract enforcement question, etc

Rather than:

• Identifying the higher-level structure such as the illocutionary form of the communication

Note: We may need to duck the necessity of defining the extent to which we support Speech Act Theory, Semiotics, etc.

Review-Feedback-SOA-RAF-Sects1-2-3-RB.doc