Re: comments on primer so far

On Mon, 2002-11-04 at 20:24, Frank Manola wrote:
> 
> Brian--
> 
> 
> Some comments on your comments (I'm not going to comment on all of them, 
>   just the ones where I either question the call, would like some more 
> input, or otherwise feel like wrangling about):
> 
> Section 1:
> [[If you were to allow me one silver bullet, one stylistic change you 
> made just because I asked for it, it would be this one(he says not 
> having read the rest of the document yet.) The first time a reader sees 
> RDF they should see a graph, not RDF/XML.

I wonder...

I think a hello-world RDF/XML document on the first page is pretty
darned important. Maybe a graph right next to it is best.

> For me, it is very important 
> to get the reader thinking about graphs, not XML, right from the get 
> go.]] (Brian's comments are deliminted by [[ ]]  )
> 
> I understand your point.  The problem is that we've just got through 
> talking about how useful RDF is for expressing information so it can be 
> exchanged between applications, and so on.  While the model/abstract 
> syntax is a graph, the only way the graph can be exchanged between 
> applications is to write them down, and the normative syntax for doing 
> that is RDF/XML.  I really do understand that the graph is the "essence" 
>   of RDF;  but it seems to me that at this point (where we say we're 
> going to be "concrete"), we want to show folks how they're actually 
> going to be writing stuff down.

[...]

> [[This section on URI's seems like a big barrier to the reader early on. 
> I'd expect a primer to introduce stuff more gradually. In style, this is 
> beginning to feel more like a text book than a primer]]
> 
> I understand.  The problem is that:
> 
> a. URIs are really fundamental;  if they don't understand that, it's 
> hard to make a number of subsequent points in sec. 2.3 (e.g., about 
> shared references and stuff)

Er... if they don't understand URIs, I think they got on
the wrong bus; they need to go learn about URIs somewhere
and come back.

> b. without having introduced fragments, and without having introduced 
> namespaces (in the maybe-to-be-deleted XML section), it's hard to 
> introduce the QName abbreviation for triples,

I don't see why somebody has to understand fragments to understand
qnames; they just need to grok concatenation.

> which means we have to 
> write them all out (and the Primer was supposed to introduce this 
> abbreviation).
> 
> [[Do we really need this about XML? Is a basic understanding of XML a 
> requirement on the reader?]]
> 
> Maybe not, and DanC complained about that too.  On the other hand, it's 
> only a page,

ONLY a page?!?!?

Each page is precious. If there's ANY way you can squeeze
a page out of the document without losing, say, 1/3rd
of your audience, I think you should.

I think you're not going to lose 1/10th of your audience
by getting rid of this page of material; anybody
who doesn't know what tags and attributes are
has gotten on the wrong bus.

> and as I said, I need (or at least I think I do) to 
> introduce the namespace stuff somewhere, and that's half of the XML 
> section.  What do you suggest?

Just assume working knowledge of XML and namespaces.
Cite the specs and some introductory articles
if you like.

I collected some "what you really need to know" citations
at the bottom of http://www.w3.org/2001/sw/WebOnt/ .

e.g.         *  XML Tutorial 1: Well-Formed XML Documents
          by Bonnie SooHoo Aug. 4, 2000 in webreview.com

-- 
Dan Connolly, W3C http://www.w3.org/People/Connolly/

Received on Tuesday, 5 November 2002 01:02:45 UTC