Here are my revised
feedback/review comments against for Sects 1, 2, 3 of the RAF spec
revision entitled “GOLD STANDARD - 2011-04-30_10pt.pdf”. This has
the line numbers from the pdf. I have also attached the Word .doc
file of this.
Cheers...
Rex
Line 299,
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 308-309
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 444, 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 477, 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
559-560+, 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 600,
Sect. 3.1.1 remove ‘s’ from perform in:
participant
may performs
Line 635.
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 703 Sect. 3.1.3.1 Suggest:
example globally unique
Internationalized Resource Identifiers (IRIs).
Rather than:
example globally unique IRIs.
Lines 705-713 Suggest breaking into
shorter sentences. Reader fatigue sets in early here, unlike
Section 2. Grammar is not wrong, just tedious.
Figure 8, 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 827, Sect.
3.1.5 change ‘constraint’ to ‘constrain in:
… does
constraint how they act if and when action covered
by the contract occurs (for
Line 829-830, 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 838, 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 833-836, Sect. 3.1.5 Please
break into shorter sentences. Long sentences seem unnecessarily
complex.
Lines 838-839, 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 853-854 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 902, 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 909-910, 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 912-913 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 929, 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 937-940, 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.
Lines 941-942, Sect. 3.2 Please
correct
Sections Error! Reference source
not found.6 and 941 3.1.7.
Lines 954-954, 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 1018-1019 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 1134 Sect 3.3.3 Suggest:
Rather than:
Note: This is consistent with Line
1291
Lines 1142-1143, Sect. 3.3.4 Suggest:
Rather than:
Note: We may need to duck the
necessity of defining the extent to which we support Speech Act
Theory, Semiotics, etc.
On 5/17/11 6:42 PM, Ken Laskey wrote:
063c01cc14fc$ce60b460$6b221d20$@mitre.org"
type="cite">
First, let me thank everyone who submitted
comments.
I have started reviewing the comments and
we run into the recurring problem of line number mismatches
when we each open the same Word doc but each formats for a
different printer. Yes, once again line numbers are all over
the place.
What is really interesting is my downloaded
Gold copy is over 6 MB but the version saved with my comments
and proposed edits is under 2 MB. It’s hard to believe the
Gold copy was 3 times the size of a saveAs.
But back to the point, I’m looking for the
easiest way of having line numbers against a common
reference. I have attached a pdf I just generated from the
Gold copy without showing any markup. If possible, I ask that
everyone go back and base their line numbers off this pdf. If
you have another suggestion for a less painful way of doing
this, then I’m game to hear suggestions.
Second, as far as making final changes, can
the section authors look at the comments against their
sections and note whether you accept the change or want to
propose an alternative. I expect the majority to be a simple
accept or simple alternative. Once that is done, we can
arrange for a few hardy volunteers to incorporate the changes
into the Gold copy. Again, if there are other suggestions,
don’t be bashful.
We can discuss details and timelines during
tomorrow’s call.
Thanks again,
Ken
---------------------------------------------------------------------------
Dr. Kenneth Laskey
MITRE Corporation, M/S H305
phone: 703-983-7934
7515 Colshire Drive
fax: 703-983-1379
McLean VA 22102-7508
--
Rex Brooks
President, CEO
Starbourne Communications Design
GeoAddress: 1361-A Addison
Berkeley, CA 94702
Tel: 510-898-0670