NF&R Review from Rinke Hoekstra on 2009-05-06 (public-owl-wg@w3.org from May 2009)

From: Rinke Hoekstra <hoekstra@uva.nl>
Date: Wed, 6 May 2009 12:22:33 +0200
To: OWL 2 <public-owl-wg@w3.org>
Message-Id: <C0B8F7B3-F1B0-4953-B122-39B7670E3A03@uva.nl>

Hi all,

This review completes my ACTION-333 (Christine, apologies for the
delay, I hadn't taken the annual Dutch April/May-holiday season into
account).

Overall I think the document is in good shape! (the examples look
great) On top of Peter's comments, there still are several things I
would like to remark. Most changes require minimal effort for maximal
impact (I hope). I could help out if necessary.

I will try to do a more detailed review of section 2 in the coming
week (to flesh out possible typos etc.)

-Rinke

The summary of my main comments is the following:

* The current situation where use cases are listed in an appendix, but
are prominently present throughout section 2, and in section 5 is not
good. Given that we moved use cases to the appendix, references to the
use cases should be removed from sections 2-4, and *either* replaced
by references to the literature *or* removed altogether (only refer
from the use cases to the features and not the other way around). The
table in Section 5 can replace the one in 7.1 and could be altered to
form the 'switchboard' between features, use cases and references to
literature (see below): these are the *real* use cases. Essentially
this means a move from a feature->use case->literature scheme to a
feature->literature->use case scheme. I understand this may be a bit
harsh/controversial, but the current solution is half-baked.

* There are some features of OWL 2 (or changes wrt. OWL 1) that are
not listed in the current version. I identified the following:
- imports & versioning (import by location etc.)
- URI -> IRI
- rdf:text
- Manchester Syntax (is mentioned, but only as example in sections
4.1 and 4.2)
- Built-in datatypes (section 4 of Syntax)
- ... more?

* I agree with Peter that the document contains too many subsections.
Promoting the subsections of section 2 to full sections would improve
readability and structure, and make the document more similar to other
documents published by the WG.

Overall:
* The numbering of sections has changed since the LC publication of
April, references from e.g. the Document Overview should be updated.

These more detailed comments concern the May 5 version of the document
[1].

Section 1
* The introduction should describe the contents of the document in the
order they appear. If the second paragraph (i.e. the last two
sentences) of this section is moved to after the first sentence of the
first paragraph, the section becomes more readable.
* I think Section 4.2 is a candidate for inclusion in the Introduction
(as Section 1.1), it demystifies a number of issues that were of
primary concern to some of the last-call commenters. As it is included
at this moment, it doesn't really fit after Section 4.1 anyway. If 4.2
is moved to 1.1, then 4.1 could become section 4 (with the title
"Syntax").

Section 2
* Perhaps it would be good if the document specifies what it means by
"Feature", apparently these are all language features, i.e. things you
may express using the language for the purpose of building an
ontology. There are other types of features (or perhaps 'aspects' of
the language), such as the profiles, versioning and the syntaxes that
are of a different type. Making this distinction explicit is
important. This could be done by renaming Section 2 to something like
"Language Constructs", or "Entities, Expressions and Axioms" (cf. the
Syntax document). Of course, this is not necessary if its subsections
are promoted to independent sections.

* I have said this before, and still stand by it: I do not see any
reason for numbering the features in this section, and think the
numbers should be removed. No other document does this, and the only
place the numbers are reused is in the "Recapitulative Table"... and
even here, just using their descriptive names is much more
informative. Secondly, not all 'features' in section 2 have a feature
number (e.g. axioms on annotation properties, top & bottom).

In a limited form, the same holds for the use cases: to me, having Use
Case #1 described in section 7.2, and Use Case #2 in section 7.3 is
unintuitive. Also, the hash symbols are superfluous.

* Minor qualm (again something I've said before). What is the reason
for the prominence of the use-case domains in the examples? To me they
don't add much, other than in the additional examples of OWL 2 use. If
it is to make the case for a feature stronger, then all features
should at least be supported by two use-case domains (or use case-
domains). Still, some have only a HCLS use case, which, in my view,
really weakens the 'case' for the feature. There are two ways out of
this, one: add examples (not cases) from other domains for each
feature, or two: remove the mention of the use case domain. In a way,
the former is related to Peter's comments on lack of rationale for
some features.

* On the references to use cases: why not use the descriptive name of
the use cases? This would improve readability. And, given Bijan's view
on the Appendix with use cases, perhaps these references should not
point to the appendix, but rather directly to the literature. (see
above)

* I don't see the distinction between sections 2.6 (other innovations)
and 2.7 (minor features). This can be one section.

* Section 2.5.1, indents do not work (I had a hard time finding
ontology annotations). I propose to split this subsubsection into two.

Section 3
* I propose to promote the introduction of Section 3.1 to be the
introduction of Section 3 as a whole. Section 3.2 could then become
Section 3.1, and Section 3.1.1, 3.1.2, and 3.1.3 may be promoted to
Sections 3.2, 3.3 and 3.4 respectively. The reason is that both the
intro to 3.1 and 3.2 are introductory material that may be of interest
to many people, while sections 3.1.1-3.1.3 are not.
* (Sidenote: in fact, I am not entirely sure that sections 3.1.1-3.1.3
are appropriate to NF&R)

Section 4
* See also section 1
* In 4.1, the indents do not work. I propose to switch to subsections.
* 'dropping the frame-like syntax' is an almost exact copy of section
12.1 in the October 2008 WD of the Syntax document. The original
version is more readable.

* "XML Schema [XML Schema] called XML_Serialization OWL/XML. " should
be "XML Schema [XML Schema] called XML Serialization."
* Reference to [UML] is not a link.

Section 5
* I looked up "Recapitulative": it is not a word. Perhaps rename to
"Overview of Features and Use Cases"
* I don't think the examples are necessary here, it only causes excess
duplication.
* This table is more informative than the one in Section 7.1, and I
suggest this table is moved to that section to replace the one that is
currently there.
* I propose a three column table: Use Case, Features, Literature
* The 'Legend' table can be dropped, as all features are referred to
using their descriptive name.
* The table should use the new table style from the css

Section 7
* See my earlier remark on numbering. If features refer directly to
literature, numbering of use cases can be dropped.
* Some use cases mention their domain, others don't (e.g. 7.11). If
you ask me, all mentions of domains can be removed: excess clutter. I
think it is a leftover from an earlier version of this document that
identified types of users etc.
* Whether a use case is used in the example of a feature is not very
interesting, in my book. I'd rather have links to all its features,
rather than just to the example. I suggest the example-links are
removed.

[1] http://www.w3.org/2007/OWL/wiki/index.php?title=New_Features_and_Rationale&oldid=23143
---
Drs Rinke Hoekstra

Homepage: http://www.leibnizcenter.org/users/rinke

Received on Wednesday, 6 May 2009 10:23:20 UTC