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 <[email protected]> To: Arthur Ryman/Toronto/IBM@IBMCA Cc: Steve K Speicher <[email protected]>, oslc-core <[email protected]>, [email protected] 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 <[email protected]> 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 <[email protected]> > To: > oslc-core <[email protected]> > Date: > 12/01/2010 02:52 PM > Subject: > Re: [oslc-core] OSLC Primer straw-man outline > Sent by: > [email protected] > > > > 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 <[email protected]> >> To: oslc-core <[email protected]> >> Date: 11/30/2010 10:31 AM >> Subject: [oslc-core] OSLC Primer straw-man outline >> Sent by: [email protected] >> >> 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 >> [email protected] >> http://open-services.net/mailman/listinfo/oslc-core_open-services.net > > > _______________________________________________ > Oslc-Core mailing list > [email protected] > http://open-services.net/mailman/listinfo/oslc-core_open-services.net > > > > > _______________________________________________ > Oslc-Core mailing list > [email protected] > http://open-services.net/mailman/listinfo/oslc-core_open-services.net >
