Re: Updated the primer

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 16:58:19 UTC