[Opportunities for Quick Examples] RE: [soa-rm] Agenda for Wednesday

["Chiusano Joseph" <chiusano_joseph@bah.com>]

Duane asked me to send information to our listserv prior to our call
today to support a suggestion that I have for improving our (already
excellent) current draft. In reading the draft, I have had the sense
that we throw (I mean that in a positive sense) so many concepts at the
reader that I believe it would help our readers if we considered
providing *quick* examples in certain places. By quick, I mean 1
sentence, possibly 2 if needed. If we think of a "comprehension meter"
inside the reader's mind, I believe this can help that meter steadily
increase as they advance from page to page.

I have gone through the first 12 pages of the spec to see where we might
have such opportunities, and have listed various concepts below, along
with (what I believe is) the first line of the spec at which they
appear. 

Line 162: Service 
Line 172: Service description 
Line 174: Effects
Line 179: Conditions
Line 180: Expectations
Line 181: Service policies 
Line 181: Service contracts
Line 196: Constraints and policies
Line 201: Service interface  
Line 203: Capability
Line 206: Data model  
Line 207: Metadata
Line 214: State change
Line 241: Standard, reference-able format
Line 277: Specific machine-process-able definitions

I don't recommend that we include example for all of these (may be
overkill), but rather that we consider picking ones that would be of
most value to the reader. There are cases in which we do provide
examples later on, but that doesn't have to preclude us from including a
quick one at the point at which the concept is introduced.

For example: 

Here is an example using the reference to "service description" on line
172. I have copy/pasted the lines that lead to it, and have added in
[]'s some additional text that would reflect this suggestion:

<Excerpt>
In order to use a service, it is necessary to know that it exists, what
is accomplished if the service is invoked, how the service is invoked,
and other characteristics. This allows prospective consumers to decide
if the service is suitable for their current needs and establish whether
a consumer satisfies any requirements of the service provider to be
permitted access. This information constitutes the service description.
[An example of a service description would be a text specification that
describes various aspects of a service].
</Excerpt>

Thanks,
Joe

Joseph Chiusano
Booz Allen Hamilton
 
700 13th St. NW
Washington, DC 20005
O: 202-508-6514 <= new office number as of 09/19/05
C: 202-251-0731
Visit us online@ http://www.boozallen.com
 

> -----Original Message-----
> From: Duane Nickull [mailto:dnickull@adobe.com] 
> Sent: Monday, October 03, 2005 12:13 PM
> To: soa-rm@lists.oasis-open.org
> Subject: [soa-rm] Agenda for Wednesday
> 
> I would like to get suggestions for topics of discussion for 
> Wednesday's call.  By now, everyone should have read the 
> complete 09 draft.  If you have not done so, please read it 
> prior to the call.  It is relatively short.
> 
> Can someone also please volunteer for note taking in advance 
> of the meeting being convened?  This will save time on the call.  
> 
> Please email suggestions back to me.
> 
> Duane
> 
> DRAFT AGENDA:
> 
> A: Administrivitis
> 1. Roll call
> 2. Determination of Quorum
> 3. Note taker appointed (someone please volunteer before the 
> call) 4. Agenda Bashing / approval of agenda 5. Approval of 
> minutes from last meeting 
> 
> B: Taskus Genuineus
> 6. Liaison Reports:
>    i: SOA Blueprints report (5 minutes max.) 7. Specification Issues:
>    I: please add here.....
> 9. Other business.
> 
> *******************************
> Adobe Systems, Inc. - http://www.adobe.com Vice Chair - 
> UN/CEFACT Chair - OASIS SOA Reference Model Technical Committee
> ******************************* 
> 
>