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 <[email protected]> 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 <[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 >> > > > >
