[oslc-core] OSLC Primer straw-man outline

[Arthur Ryman]

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