Comments for WD-rdf-primer-20030123

Here are minor editorial comments for your "RDF Primer" Last Call
Working Draft [1].

Minor typos, some global:
s/web/Web/
s/web site/Web site/
s/web page/Web page/
s/web logs/Web logs/
s/webmasters/Webmasters/
s/web browsers/Web browsers/
s/N-triples/N-Triples/
s/tradeoff/trade-off/
s/ex:Motorvehicle/ex:MotorVehicle/
s/HTML Meta elements/HTML <code>meta</code> elements/
s/lower case/lowercase/
s/Copyright @ 1998 Eric Miller/Copyright © 1998 Eric Miller/
s/stylesheets/style sheets/ (when you mean CSS and not XSL)

Please avoid we (see http://www.w3.org/2001/06/manual/#ref-PRONOUNS).
For example, you could say "Section 5.3 says more about this point" in
place of "We will say more about this point in Section 5.3."

Please avoid you (see http://www.w3.org/2001/06/manual/#Translations).

Omit <em> as much as possible in the prose. A little emphasis goes a
long way. Reserve most italics for names of parts of the RDF language.

Please use international examples, something like "Course 6.001 has the
students Carlos, Phuong, Vasiliy, Maria, Mohamed, and Françoise" and
"Piazza della Repubblica - 80122 Napoli, Italy" and "Musée du Louvre
75058 Paris Cedex 01." Use postal codes in place of ZIP codes.

Please use only the IANA-registered domains example.com, example.net
and example.org for examples per RFC 2606. An example of what could
happen to dlib.org, wanderlust.com, geneontology.org et al. is
available on request. I recommend skipping the prismstandard.org URIs
and namespace discussion and concentrating on what PRISM does. If you
need something evocative use a machine name something like
http://DLIB-magazine.example.org and http://ratings.example.net

I think if you plan to introduce concepts like URIs, URLs, HTML, XML,
and namespaces (Appendixes A and B) that it would be worthwhile to
introduce the terms semantics, syntax and schema, and maybe
serialization so newcomers will know what each RDF spec does. You could
this up front, in as few words as possible (say less than a sentence
each).

I would move the last part of the introduction starting with "The
following documents contribute to the specification of RDF:" to the
beginning. Due to the complexity of having six parts, readers need an
introduction to the RDF specifications as much as to RDF.

In 2.1, start out with URI not URL (so you don't have to undo that
later).

In 2.2, "qualified name (or QName)" needs a link to a reference for
Namespaces in XML.

Following are minor suggestions based on a quick read. I will try to
read the Primer at a later maturity level hoping to catch everything.

     As noted earlier, the normative (i.e., definitive) RDF
     specification describing these concepts is the RDF Concepts and
     Abstract Syntax [RDF-CONCEPTS], which should be consulted for
     further information. Together with the RDF Semantics
     [RDF-SEMANTICS] document, [RDF-CONCEPTS] provides the definition of
     the abstract syntax for RDF, together with its formal semantics
     (meaning).
(two "together withs") could read:
     As noted earlier, the normative (i.e., definitive) RDF
     specification describing these concepts is the RDF Concepts and
     Abstract Syntax [RDF-CONCEPTS], which should be consulted for
     further information. The RDF Semantics [RDF-SEMANTICS] document
     provides RDF's formal semantics (meaning).

This sentence is too long:
     This may be done either by modifying the RDF document in which the
     resource was originally described, to add the properties and values
     needed to describe the additional information, or, as this example
     illustrates, by creating a separate document, and providing the
     additional properties and values in rdf:Description elements that
     refer to the original resource via its URIref using rdf:about.
it could read:
     This may be done either by modifying the RDF document in which the
     resource was originally described, to add the properties and values
     needed to describe the additional information. Or, as this example
     illustrates, a separate document could be created, providing the
     additional properties and values in rdf:Description elements that
     refer to the original resource via its URIref using rdf:about.

3.3 RDF/XML Summary can go before the examples to save the reader time.
Its text:
     The examples above have illustrated some of the basic ideas behind
     the RDF/XML syntax. These examples provide enough information to
     enable you to begin writing useful RDF/XML. For a more thorough
     discussion of the principles behind the modeling of RDF statements
     in XML (known as striping), together with a presentation of the
     other RDF/XML abbreviations available, and other details and
     examples about writing RDF in XML, you should refer to the RDF/XML
     Syntax Specification [RDF-SYNTAX].
could read something like what follows. (Syntax has very little more
information on striping, abbreviations and examples than the Primer.)
     The examples below illustrate some of the basic ideas behind
     the RDF/XML syntax. To go beyond this introduction, please refer
     to the normative RDF/XML Syntax Specification [RDF-SYNTAX].

Here's another long sentence:
     Moreover, depending on how the application interprets the property
     descriptions, a description of an instance might be considered
     valid either without some of the schema-specified properties (e.g.,
     you might have an instance of ex:Book without an ex:author
     property, even if ex:author is described as having a domain of
     ex:Book), or with additional properties (you might describe an
     instance of ex:Book with an ex:technicalEditor property, even
     though you haven't described such a property in your particular
     schema.)
It could read:
     Moreover, depending on how the application interprets the property
     descriptions, a description of an instance might be considered
     valid either with or without some of the schema-specified properties.
     For example, an instance of ex:Book might not have an ex:author
     property, even if ex:author is described as having a domain of
     ex:Book, or an instance of ex:Book might have an ex:technicalEditor
     property, even though it isn't described in a schema.

[1] http://www.w3.org/TR/2003/WD-rdf-primer-20030123/

Best wishes for your project,
-- 
Susan Lesch           http://www.w3.org/People/Lesch/
mailto:lesch@w3.org               tel:+1.858.483.4819
World Wide Web Consortium (W3C)    http://www.w3.org/

Received on Monday, 24 February 2003 00:50:40 UTC