[oslc-core] OSLC Primer straw-man outline

Fri Dec 3 09:32:12 EST 2010

Arthur, Thanks for being very specific.

Seems that we need two documents:
   - OSLC Overview
   - OSLC Primer

As you can see from my proposed outline, I think both are high
priority concerns and deserve to be completed at one time as one
document or a pair of documents.

What do others think about priority? Should we focus exclusively on a
Primer first, or push both ideas forward now?

- Dave

On Thu, Dec 2, 2010 at 3:55 PM, Arthur Ryman <ryman at ca.ibm.com> wrote:
> 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
>>
>
>
>
>