Re: Updated the primer

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
> 
> 
>

Received on Saturday, 31 March 2012 17:31:29 UTC