Re: Updated the primer

I have made, essentially, the changes below. New version of the Primer are now updated at

http://www.w3.org/2010/02/rdfa/sources/rdfa-primer/Overview-src.html
http://www.w3.org/2010/02/rdfa/sources/rdfa-primer/Overview.html

Dated 2nd of April

Thanks

Ivan


On Mar 31, 2012, at 19:31 , Ivan Herman wrote:

> Grant,
> 
> that makes a lot of sense indeed. I will give it a second thought, but I my first reaction is to follow your advise (to be done sometimes next week).
> 
> Ivan
> 
> ---
> Ivan Herman
> Tel:+31 641044153
> http://www.ivan-herman.net
> 
> (Written on mobile, sorry for brevity and misspellings...)
> 
> 
> 
> On 31 Mar 2012, at 18:57, "Grant Robertson" <grantsr@gmail.com> wrote:
> 
>> Ivan,
>> 
>> Apparently I missed previous iterations of the updated Primer document. All
>> I have to compare is the document listed here:
>> http://www.w3.org/TR/2011/WD-rdfa-primer-20111208/ and the one listed here:
>> http://www.w3.org/2010/02/rdfa/sources/rdfa-primer/Overview-src.html.
>> 
>> I like that you limited your initial discussion - up through Section 5 - to
>> features that are available in RDFa Lite 1.1. However, as a reader, I found
>> it confusing that the section titled "RDFa Lite and Full" is actually NOT
>> about RDFa Lite at all. It is about the added features which RDFa Core has
>> OVER AND ABOVE what is in RDFa Lite. I was looking for information about
>> RDFa Lite, so I followed the link in the table of contents that said "RDFa
>> Lite" and instead found that the first sentence tells me that I should have
>> read all the previous sections. You should not lead the reader on a wild
>> goose chase like that. 
>> 
>> I propose the following changes to the titles of the sections in order to
>> make it more clear what the reader will be getting when they read the
>> document:
>> 
>> Take all of sections 2 - 6 and put them under one heading called "Using
>> RDFa." This is the main part of the document and everything else is
>> ancillary to that. Therefore, make it stand out. If I were a first time
>> viewer of this document and wanted to learn about RDFa, a section titled
>> "Adding Machine Readable Hints to Web Pages" is not what I would be looking
>> for. I want to know how to USE this thing.
>> 
>> Take Sections 2-5 and put them under a further sub-heading called "The
>> Basics of RDFa: RDFa Lite." Then, in the introductory sentence for that
>> section say, "This section explains RDFa using a subset of RDFa called 'RDFa
>> Lite.' This subset was chosen because it makes it easier to learn the
>> concepts without too much complexity. Many web authors will never need to
>> learn any more than this 'Lite' subset." 
>> 
>> Now, rename Section 2 to "First Steps: Adding Machine-Readable Hints to Web
>> Pages" thus directing readers who are just getting started to this section.
>> 
>> Rename Section 3 to "Exploring Further: Social networks" so you can save the
>> "Going Deeper" metaphor for when you talk about the additional features in
>> RDFa Core.
>> 
>> Finally, rename Section 6 to "Going Deeper: RDFa Core"
>> 
>> 
>> In summary, the new Organizational structure of the document would be
>> something like this:
>> 
>>   1. Introduction
>>       1.1 HTML vs. XHTML
>>       1.2 Validation
>>   2. Using RDFa
>>       2.1 The Basics of RDFa: RDFa Lite
>>            This section introduces and explains RDFa using a subset
>>            of RDFa called 'RDFa Lite.' This subset was chosen because
>>            it makes it easier to learn the concepts without too much
>>            complexity. Many web authors will never need to learn any
>>            more than this 'Lite' subset.
>> 
>>            2.1.1 First Steps: Adding Machine-Readable Hints to Web Pages
>>                2.1.1.1 Hints on Social Networking Sites
>>                2.1.1.2 Links with Flavor
>>                2.1.1.3 Setting a Default Vocabulary
>>                2.1.1.4 Multiple Items per Page
>> 
>>            2.1.2 Exploring Further: Social networks
>>                2.1.1 Contact Information
>>                2.1.2 Describing Social Networks
>> 
>>            2.1.3 Internal References
>> 
>>            2.1.4 Using Multiple Vocabularies
>>                2.1.4.1 Repeating properties
>>                2.1.4.2 Default Prefixes (Initial Context)
>> 
>>       2.2 Going Deeper: RDFa Core
>>           2.2.1 Using the content attribute
>>           2.2.2 Datatypes
>>           2.2.3 Alternative for setting the context: about
>>           2.2.4 Alternative for setting the property: rel
>> 
>>   3. RDFa Tools
>>   4. You Said Something about RDF?
>>       4.1 Custom Vocabularies
>>   5. Acknowledgments
>>   A. References
>>       A.1 Normative references
>>       A.2 Informative references
>> 
>> 
>> 
> 


----
Ivan Herman, W3C Semantic Web Activity Lead
Home: http://www.w3.org/People/Ivan/
mobile: +31-641044153
FOAF: http://www.ivan-herman.net/foaf.rdf