Re: ACTION-333 Quick Review of Quick Reference Guide

A first quick comment about links.

- NF&R says what a new feature is and not only why a new feature has
been added. If it turns out that NF&R has unvoluntary been too much
cut and gives a wrong impression, it's urgent to say it. I will revert
and reintroduce some content of previous version.

- QRG links
to simplify, there are 3 profiles of QRG readers : (1) newbies, (2)
OWL 1 familiar users, (3) advanced

Links useful for
(1): to Primer + NF&R for new features
(2): to NF&R
(3): no "instructional" (Primer or NF&R)  but only "technical"
documents i.e. normative specs (syntax and semantics).

I suggest to keep all links to NF&R and Primer. Otherwise if you
consider that they are "not very useful", remove both links to NF&R
and Primer.

2009/4/23 Peter F. Patel-Schneider <pfps@research.bell-labs.com>:
>
>        Quick Review of QRG
>
> I reviewed the version of 22 April 2009.  This version has the link
> column up to about Section 2.2.1.
>
> General comments:
>
> - Satisfying the following comments will require quite large changes to
>  the document.  A re-review will be needed.
>
> - Moving the links to a separate column is a bad idea.  It consumes
>  extra space to no good effect.  Links in the QRG should be from the
>  relevant information itself, as they used to be.
>
> - Links to NF&R are not very useful in the QRG.  Users of this document
>  will not be interested in why a new feature had been added to OWL 2.
>  Instead they will be interested in what the feature is (and thus the
>  old links from the FS column are useful) and in how to use the feature
>  (and thus the links to the Primer are useful).  I suggest that all
>  links to NF&R be removed.
>
> - Links to the RDF Mapping do not provide any useful information and
>  should also be used.  This document itself provides the information
>  needed about the mapping, and in a form much more likely to be
>  comprehensible by the readers of this document.
>
> - The document is missing named classes, properties, and individuals.
>  Lines like the following should be added:
>  Named class  U  U
>  In some places names are required but the document does not
>  distinguish between names and expressions.  The places that I noticed
>  where names are required are 2.6 Declarations and 2.7 Annotations.
>
> - This document should use terminology from the normative OWL 2
>  documents.  This requires at least some changes to the following
>  terminology:
>  OWL class -> class expression
>  object property -> object property expression
>  I second Christine's comment to use the same short forms as in SS&FS,
>  in general, but it may be that C is better than CE, if only to save
>  space.
>
>  I suggest the following start of a fix for the notation paragraph:
>
>    We use the following notation conventions: "C" is a class
>    expression, "D" is a data range, "P" is an object property
>    expression, "R" is a data property, "A" is an annotation property,
>    "a" is an OWL individual, "v" is a literal, and "n" is a
>    non-negative integer. All of the previous can have subscripts.
>    "_:x" is a blank node.  "(a1 ... an)" is an RDF list.
>
>  Then use subscripts where Q, S, and v were used before.
>
> - There are some awkward sentences in the document.  I haven't changed
>  them, but a final pass should be made after the content is fixed.
>
> - Subsections should be used sparingly.  I suggest no sub-sub-sections
>  (2.1.1, etc.) at all.
>
> - This document does not really need to address n-ary data ranges.  I
>  suggest removing all mention of n-ary data ranges and their support.
>
> - In some places the document uses explicit iteration (n-ary individual
>  equality) and in some places it uses implicit iteration (equivalent
>  properties).  Only one should be used.  I suggest implicit.
>
> - The document is missing some constructs.  I noticed:
>  - prefixes
>  - datatype definitions
>  - names, literals
>  - individuals - named and anonymous
>
> - It would probably be better to merge all the datatype and data range
>  stuff into one section.  The built-in datatypes could be more
>  succinctly presented by just listing the xsd datatypes.
>
> Specific comments:
>
> - The abstract needs to be completely rewritten, to be something like:
>
>  This document provides a quick reference guide to the OWL 2 language.
>
> - Section 1 should be renamed to "Prefixes" and the first sentence
>  changed to "The standard prefixes in OWL 2 are:" to conform with the
>  wording in the normative OWL 2 documents.
>
> - "_:x" is a blank node. All of these can have subscripts.
>
> - The link for RDF lists should probably point to Turtle or some other
>  place that uses this syntax for RDF lists.
>
> - "all OWL individuals" -> "universal class" (maybe)
>
> - The "Every owl:Restriction is an owl:Class." sentence is not needed at
>  all.
>
> - The presentation of cardinalities should be made easier to understand.
>  I suggest something like
>
>                    |                              | _:x rdf:type owl:Restriction.
>                    | ObjectExactCardinalty(n P)   | _:x owl:onProperty P.
>                    |                              | _:x owl:cardinality n.
>  exact cardinality | -----------------------------|------------------------
>                    |                              | _:x rdf:type owl:Restriction.
>                    | ObjectExactCardinalty(n P C) | _:x owl:onProperty P.
>                    |                              | _:x owl:qualifiedCardinality n.
>                    |                              | _:x owl:onClass C.
>
> - "<x> Properties are instances of owl:<x>Property" should be changed to
>  just "<x> Property Expressions".  The last bit is not part of the FS,
>  and in any case doesn't add any information.
>
> - "universal <x> property" and "empty <x> property"
>
> - The range of a datatype property axiom is a data range, not a class.
>
> - Data range intersection and union are switched up in the table.
>
> - positive object property assertion needs to indicate that P is an
>  object property, not an object property expression.
>
> - A and AP are both used for annotation properties.  Only one should be.
>
> - The section on Annotations needs work.  Object annotations are on
>  names only, for example.  The full fixing up of this section should be
>  done after some of the above changes are made.
>
> - The FS for deprecation doesn't need the short form - just write out.
>  Deprecation can be used for individuals as well.
>
> - The section on ontologies should not say "Annotations of Ontologies".
>
> - This is a quick reference guide and does not need to mention all the
>  arcana.  Therefore the section on deprecation should be deprecated.
>
> Tyops:
>
> - I fixed a few typos.  If the document is reverted these may need to be
>  fixed:
>  Abstract: his -> This
>  2: an rdf list.
>  2.1: _:x  owl:hasValue a.
>       an n-ary data range
>  2.2.1: bottom  object property
>  2.5: a rdf:type C
>
>



-- 
Christine

Received on Thursday, 23 April 2009 08:03:59 UTC