Re: Feedback on RDFa Primer

Manu,

Great feedback, this is very useful. I specifically appreciate the
points about the need to explain briefly what an RDF triple is, and
conveying clearly that this is *not* a syntax document. If you're
interested in helping me write some of those chunks, that would be
fantastic.

I disagree a bit with your outline: past comments urged us to tell a
fairly complete story. A Primer should give you enough material to "get
started." So I'm not sure we should break out every case study into a
separate document and have such a short, mostly high-level Primer. We
need real examples, real markup, and real use cases.

I do agree, however, that we should keep the inline examples short and
to-the-point. So I'll try to restructure this a bit, and leave some
sections open for you to fill in? We can also coordinate with a phone
call, if you'd like,

-Ben

Manu Sporny 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/
> 
>

Received on Thursday, 30 August 2007 22:01:07 UTC