Re: Feedback on RDFa Primer

Hi Manu,

These are all interesting points, and I would agree with most. I
especially like the idea of linking through to more detailed documents
that relate to the kinds of tasks that authors want to perform.

But I would slightly disagree with (a) the idea that triples should be
brought to the front, and (b) that there are too many HTML examples.

Whilst the 'goal' of RDFa is certainly to allow RDF to be 'carried' by
any XML-based language, at the moment the clear focus is HTML/XHTML.
You could say that we're dealing with a dialect of RDFa, namely
XHTML+RDFa.

This dialect is actually much easier to explain than a more general
RDFa syntax, since HTML already has a number of metadata features that
people use every day, and they do so without having to understand
triples. Just about every HTML author is already familiar with <meta>
and <link> for example. There's less awareness of of the use of @rel
and @rev on <a>, but it's still something that is not far out of
people's experience.

So if the primer was to change, I would argue for it to change so that
it begins with examples that are almost purely ordinary HTML, to
remind people of the status quo. Then we'd explain triples, but merely
as a kind of shorthand for expressing the metadata that we're able to
create. The main point we'd be making is 'look, you've already been
doing this stuff for years'.

After that I'd suggest that we gradually incorporate the new
attributes, beginning with @property, @content and @datatype (very
easy to understand), before moving on to @instanceof (a bit trickier,
but not that bad), and of course @about.

One last thing is that I think we need a few graphics in there. I wish
I could draw, because I think RDFa could be explained visually, *very*
easily.

Thanks for the great input.

All the best,

Mark


On 30/08/2007, Manu Sporny <msporny@digitalbazaar.com> wrote:
>
> 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/
>
>
>


-- 
  Mark Birbeck, formsPlayer

  mark.birbeck@formsPlayer.com | +44 (0) 20 7689 9232
  http://www.formsPlayer.com | http://internet-apps.blogspot.com

  standards. innovation.

Received on Thursday, 30 August 2007 22:12:52 UTC