Feedback on RDFa Primer

Ben, here's some extra feedback on the RDFa primer[1]. In general, all
of the information in there is important, but I believe it needs to be
restructured to deliver the RDFa message more clearly. I am not familiar
with W3C Primer document requirements, so these suggestions might fly in
the face of what is required by the W3C for a Primer document.

Personal Experience
-------------------

Not having much experience with RDF/RDFa, I started a month ago with the
RDFa Primer... which I stopped reading after the 4th page because I
thought I was in the wrong place. It's 15 pages of printed text (in 10
point font). I was hoping for an introductory document and felt that I
had found the RDFa syntax document.

Goals for the Primer
--------------------

- It should express how simple and powerful RDFa is, and it should do
  this in one to two pages. The rest should focus on refining
  understanding.
- We want to reassure everybody that you don't need to be a website
  designer to use RDFa:
      "If you can write HTML, RDFa will be a piece of cake."
- Focus on RDFa concepts, not on RDFa syntax.
- Use very minimalistic examples to get the concept across.
- Give readers the option of delving into more thorough examples if
  desired... but don't require it to understand RDFa basics.

Current Problems with the Primer
--------------------------------

- Does not explain what an RDF Triple is up-front. Understanding Triples
  is vital to understanding how RDFa works.
- Too many HTML examples.
- Too many technical/syntax details.

Ideal Layout
------------

- Why RDFa is Useful (1-2 paragraphs)
- Short Example of RDFa Markup (1-2 paragraphs, use FOAF)
- Explanation of Triples (2-3 paragraphs)
- Show which Triples are generated with the FOAF example above
- How Web Browsers Use the Generated Triples
- Explain @about, @instanceof, @resource in more detail.
- Links to External Use Cases
   - Publishing An Event
   - Publishing Contact Information
   - The Complete HTML with RDFa
   - RDFa with Limited HTML control
   - foaf
   - ical
   - vcard-rdf
   - haudio-rdf
   - shutr
- Bibliography
- Acknowledgements

The document should probably be no greater than 5-6 pages... which I
think is very do-able. I could re-arrange the current primer as a
further example, if you'd like?

Perhaps we should think of a couple of supporting documents... where do
you go once you've read the primer? My thought, is that you go to one of
the examples/external use case pages. But where after that? The RDFa
Syntax and Reference Manual?

I'm posting this to the mailing list because I might be missing
something very basic, or my understanding of what a primer should
accomplish might not be in line with what others on this list think.
Thoughts?

-- manu

[1] http://www.w3.org/TR/xhtml-rdfa-primer/

Received on Thursday, 30 August 2007 21:21:17 UTC