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 >
