[oslc-core] OSLC Primer straw-man outline

[Arthur Ryman]

Dave,

The outline you proposed contains material that is too general to be in a 
Primer. It is useful information, but should be in other documents, e.g. 
Guides or Overviews. A Primer should be focused on how to use a spec. It 
should be scenario based, developing an example, and explaining features 
of the spec as required, motivated by actual usage.

I think the following topics are valuable, but are too general for a 
Primer:

Overview of OSLC 
Motivation 
Approach 
Brief history 
Assumptions 
Developer familiar with web development 
Technical approach REST + RDF 
Motivation 
Basics of REST 
Basics of RDF 
How they complement one another 
How OSLC Services work 
Core and Domain specifications 
Defining and representing resources 
Finding and fetching resources 
Creating and updating resources 
Previews and Delegated UI 
World tour of OSLC domains 
Background & motivation 
The dozen domains 
Guide to resources defined 

The ones after those get down to actual hands-on usage.

Regards, 
___________________________________________________________________________ 

Arthur Ryman, PhD, DE

Chief Architect, Project and Portfolio Management
IBM Software, Rational
Markham, ON, Canada | Office: 905-413-3077, Cell: 416-939-5063





From:
Dave <snoopdave at gmail.com>
To:
Arthur Ryman/Toronto/IBM at IBMCA
Cc:
Steve K Speicher <sspeiche at us.ibm.com>, oslc-core 
<oslc-core at open-services.net>, oslc-core-bounces at open-services.net
Date:
12/01/2010 05:02 PM
Subject:
Re: [oslc-core] OSLC Primer straw-man outline



I agree with you Arthur, or at least I think I do. Does the outline I
proposed meet your requirements for a primer? Are there section titles
that worry you? What would you change?

And I also agree with Scott: I'd like the examples to be real ones,
e.g. OSLC-CM.

- Dave



On Wed, Dec 1, 2010 at 3:18 PM, Arthur Ryman <ryman at ca.ibm.com> wrote:
> IMHO, the primary purpose of a Primer should be to teach people how to 
use
> the specifications, without having to read the specifications in detail.
> This means that the Primer should be very pragmatic and have lots of
> realistic examples. Ideally, the Primer should progressively reveal more
> detail, starting with a simple example and building on it, showing how
> each feature of the specification is motivated by some real-world
> requirement.
> Ideally, the Primer should use a consistent, unifying, realistic 
scenario
> as the basis for the examples - no foo's or bar's. The Core spec 
currently
> uses a Blog scenario. That could be elaborated.
> The Primer I most frequently use is the XML Schema Primer. Notice the
> absence of generalities and the abundance of concrete examples.
> Lengthy general information should not be in the Primer. It should be in
> other documents, e.g. Guides or Overviews.
>
> Regards,
> 
___________________________________________________________________________
>
> Arthur Ryman, PhD, DE
>
> Chief Architect, Project and Portfolio Management
> IBM Software, Rational
> Markham, ON, Canada | Office: 905-413-3077, Cell: 416-939-5063
>
>
>
>
>
> From:
> Steve K Speicher <sspeiche at us.ibm.com>
> To:
> oslc-core <oslc-core at open-services.net>
> Date:
> 12/01/2010 02:52 PM
> Subject:
> Re: [oslc-core] OSLC Primer straw-man outline
> Sent by:
> oslc-core-bounces at open-services.net
>
>
>
> I think this is a pretty comprehensive list.
>
> Though, I think this should be divided into 3 main primers/overviews 
based
>
> on who the consumers of this information are which I believe would be:
>
>   1. New to OSLC - know very little about it and don't want to know too
> much (at the moment)
>   2. Architecture / Motivation of OSLC - want to know more, sort of
> modeled off of Architecture of WWW
>   3. Implementers - index of resources and content to help
>
> Perhaps there could be more detailed version of #1 where it includes:
>
>    * OSLC Domains - want to know how all domains come together: scope of
> each domain, resource interaction diagram, etc
>    * OSLC Community - I want to get involved, who is involved, how does
> it work
>
> For implementation, I wonder how much we really want to do at
> open-services.net verses reference other works: open source projects, 
IBM
> developerWorks articles, videos, etc.
>
> Thanks,
> Steve Speicher | IBM Rational Software | (919) 254-0645
>
>
>> From: Dave <snoopdave at gmail.com>
>> To: oslc-core <oslc-core at open-services.net>
>> Date: 11/30/2010 10:31 AM
>> Subject: [oslc-core] OSLC Primer straw-man outline
>> Sent by: oslc-core-bounces at open-services.net
>>
>> We've discussed the need for an OSLC "Primer" document to introduce
>> OSLC to those new to OSLC, REST, RDF and/or related technologies and
>> to explain to them how OSLC and the domains work. I think there is
>> general consensus that development a primer is high-priority, so I've
>> gone ahead and put together a straw-man outline for such a primer
>> here:
>>
>>    http://open-services.net/bin/view/Main/OslcPrimer
>>
>> Please take a look and let me know you think either here or tomorrow
>> in the Core workgroup meeting.
>>
>> Thanks,
>> - Dave
>>
>> _______________________________________________
>> Oslc-Core mailing list
>> Oslc-Core at open-services.net
>> http://open-services.net/mailman/listinfo/oslc-core_open-services.net
>
>
> _______________________________________________
> Oslc-Core mailing list
> Oslc-Core at open-services.net
> http://open-services.net/mailman/listinfo/oslc-core_open-services.net
>
>
>
>
> _______________________________________________
> Oslc-Core mailing list
> Oslc-Core at open-services.net
> http://open-services.net/mailman/listinfo/oslc-core_open-services.net
>