Re: Primer updated with a Changes section

Hi Ben,

I'm afraid that coming back to the Primer with fresh eyes, I find that
it doesn't really work. Sorry about that...

In particular, it's not really clear what the document is trying to
achieve. At times it seems to be trying to get the reader up and
running quickly with some examples. But then at other times it seems
like the aim is to provide the reader with a simplified introduction
to all of the RDFa concepts and syntax. (A lot of the section headings
are concept-related.) Then with the 'RDF Correspondence' section it
seems to be aimed at implementers.

I'm not saying that the document can't do all of these things, but I
don't believe it's clear that it achieves any of these goals
effectively, at the moment.

So I wonder whether we should tackle this in two stages. As long as
the document is in line with the Syntax document--and as far as I can
see it is--then it's still a very useful document as it stands, and
people will gain from reading it.

But after that I think we need to work out what it is that we want
from this document, and who we're aiming at.

For example, if we decide that we do actually need a 'simplified
syntax document', then maybe that should be distinct from this
particular primer. It would certainly be the place where we can use
and explain the terminology that's in the Syntax document.

Or we might decide that we want a document that walks the reader
through lots of worked examples, and so helps people get up and
running quickly. If so, maybe that's a standalone document in its own
right, independent of some 'simplified syntax', that provides the
walkthroughs, and nothing more? (In other words, maybe we need
separate documents for "RDFa Syntax Primer" and "RDFa Primer".)

Or maybe the distinction is between an authors' primer and a
developers' primer? The authors' primer might focus purely on examples
and walkthroughs, using FOAF, calendar events, etc., with lots of
mark-up that they can cut-and-paste. The developers primer on the
other hand might talk about the syntax, the triples generated, etc,
helping those who want to build server-side processing tools, parsers,
browser plug-ins, and so on, to get up to speed.

There may be other suggestions...I'm merely saying that I think we
need to be clear on our goals before we can really fine-tune this
document.

Regards,

Mark

On 06/03/2008, Ben Adida <ben@adida.net> wrote:
>
>
>  Hi all,
>
>  I just added [Section 6. Changes] to the Primer:
>
>  http://www.w3.org/2006/07/SWD/RDFa/primer/
>
>  which I wrote up based on the XML diff of the two Overview.xml files.
>  Little has changed. If you have time, please review it today or
>  tomorrow! Look for examples that I forgot to fix!
>
>  Thanks,
>
>
>  -Ben
>
>


-- 
  Mark Birbeck

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

  x-port.net Ltd. is registered in England and Wales, number 03730711
  The registered office is at:

    2nd Floor
    Titchfield House
    69-85 Tabernacle Street
    London
    EC2A 4RR

Received on Friday, 7 March 2008 11:58:42 UTC