Re: review of document-overview

From: Sandro Hawke <sandro@w3.org>
Subject: review of document-overview
Date: Tue, 10 Mar 2009 00:13:36 -0400

> I don't think we assigned reviewers, and I we're scheduled to make a
> publication decision in about 36 hours; so I did a review, and here it
> is.

Hmm.  I read the document very early this morning (for me), and made
some edits, after noticing the Britishisms.  Once I started, I kept
going for a while.  :-)

> With editorship of this document a little vague, and Ian unavailable
> this week, I'm not quite sure how to proceed.  Here's my suggestion: if
> you agree with one of my comments, reply with a "+1" to it.  If you
> don't, reply with a "-1" and/or explanation.  Any of my proposed changes
> which get at least one +1 and no -1's, I'll try to implement.  (My
> timeline for this will depend on when/how folks reply.)  (In some cases,
> I make disjunctive proposals, and you should clarify which option you're
> approving or objecting to.)
> 
> My review is on this version:
> http://www.w3.org/2007/OWL/wiki/Document_Overview?oldid=18827
> 
> A few of these (like what documents to link to, and fixing the abstract)
> are show-stoppers; IMO they really have to be addressed before
> publication.   I'd like to see them all addressed.
> 
>         -- Sandro
> 
> ================================================================
> 
> Document Overview
> 
> * The abstract needs to be handled as a special case; right now the
>   first paragraph gets weird, talking about itself in the third
>   person.
> 
> * I think the title should be
> 
>      OWL 2 Web Ontology Language
>      Part 1: Document Overview

-1  I thought that we had only agreed to number the rows of the table.

> SECTION 1
> 
> * "Ontologies are formalised" -> "Ontologies are formalized"

May have missed this one.  +1

> * OWL 1 was developed by the Web Ontology WG, not the OWL WG.

+1

> SECTION 2 (Overview)
> 
> * "At the top are various concrete syntaxes that can be used to"
>                                            ^ discussed in section 2.2

+1

> * "At the bottom are the two semantic specifications"
>                                                     ^ discussion in
>                                                     seciton 2.3

1+ :-)

>    (without these forward references, the diagram is unexpectedly
>    baffling, I think)
> 
> * I'd make the diagram bigger -- maybe 700px across instead of 600,
>   but maybe that's just me.     Also a little color might be nice.
>   Ivan, will the source work in InkScape?

NC

> SECTION 2.1 Ontologies
> 
> * (here and elsewhere) "OWL 2 Specification" is a really bad reference
>   name for Structural Specification and Functional-Style Syntax.  I
>   don't know what we should call it, but calling part 2 of the OWL 2
    	       	       	      	       	   	   ^?
>   specification "specification" is ... not okay.  (Yes, I know we've
>   done this in our other publication so far; I didn't want to make a
>   stink then because we'd argued too much about naming, but now looking
>   at it again from the perspective of someone coming fresh to our
>   documents, ...  "No!")
> 
>   There's an argument that we should always refer to other parts of the
>   OWL 2 spec using the approved shortname, in which case this reference
>   would be "owl2-syntax", but ... that's a pretty confusing name, too,
>   especially in a sentence explaining how it's not about syntax.
> 
>   I think my favorite would be "OWL2 Structures".  Maybe we should
>   change the shortname from owl2-syntax to owl2-structures, too.

+1 to OWL 2 Structural Specification (Some of my edits may have
alleviated this problem)

> SECTION 2.2 Syntax
> 
> * "serialisation" (UK spelling)

Fixed.

> * Maybe do a table of the syntaxes and their properties?
>   (Name, Specified In, Required?, Description)

-0.1, simply because this document should be !*SHORT*!

> SECTION 2.3 Semantics
> 
> * "OWL 2 Ontologies that are interpreted using the RDF-Based Semantics
>   are called 'OWL 2 Full' ontologies. " and the last paragraph
>   paragraph...
> 
>   I think OWL Full is/should be the name of a syntactic subset --
>   specifically the trivial subset that is the full language.  The
>   choice of semantics is orthogonal.

Hmm.  Then how to label RDF graphs under the RDF-Based Semantics?  OWL 2
Full works and is consistent with the usage in OWL 1.  I made some edits
that may alleviate this problem.

> * On the editor's note -- we don't need to characterize it here; it's
>   too technical for this.

+1

We could say something like 
	OWL 2 DL ontologies can be mapped into RDF and back again
	without change in meaning.
but I'm not sure where this would fit in.

> * So, the last paragraph needs lots of work, since it conflates
>   syntactic subset (OWL DL) with choice of semantics (Direct
>   Semantics).

My edits may alleviate this.

> * I think it would help to have a table like this, to help make the
>   point about the tradeoffs between the semantics, and their
>   relationship with syntactic subsets...
>       http://www.w3.org/People/Sandro/owl2-matrix
>   but it still needs some work, and maybe can never be accurate
>   enough to be more helpful than harmful.

-1 (shortness is beautiful)

> SECTION 3: Profiles
> 
> * I'd prefer this numbered as 2.4.  I think it's more at the same level
>   as 2.1, 2.2, and 2.3 and 2/4/5.  ACTUALLY, I think I'd put this BEFORE
>   Semantics, so we can do the table of Profiles-vs-Semantics.  The
>   profiles can be done without talking about the two semantics.

+1 to renumbering
+0 to moving

> * I'd like to include a Venn Diagram, perhaps a version of 
>   http://www.w3.org/People/Sandro/owl2-profiles-doc
>   without the roll-overs, and in black-and-white (or make the other
>   diagram be in color).

-1 (shortness is beautiful)

> * I'd like to make it more clear that the profiles are syntactic
>   subsets -- and that there may be benefits for sticking within those
>   subsets -- and nothing magical than that.

+1 to 
  OWL 2 Profiles [OWL 2 Profiles] are *syntactic* sub-languages of OWL 2

> * In particular, DL is a syntactic subset of OWL 2, even though it's
>   not described in Profiles.   That should be shown in this section.

-1, at least without some major surgery on the document

> SECTION 4: Differences between OWL 2 and the previous version of OWL 
> 
> * Very clunky title...  How about "What's New In OWL 2"?  (it even
>   rhymes)

+0.5

> * Maybe subsections, "What's the Same" and "What's New", which seems to
>   be the text here, if divided into groups the same size as the
>   subsections in 2.

+0.01 - Not really needed

> * The references here (and in some other places) are not preceeded by
>   a space, giving us stuff like "Syntax[OWL 1", which seems
>   typographically wrong to me...

Fixed

> * The XML syntax for OWL 1 seems oddly described, and the link seems
>   wrong.

I think that all of the OWL 1 ... links are inoperable.
I would change the wording to "An XML syntax was ...."

> * Obviously the editor's note "Editor's Note: Is this correct? Or are
>   there corner cases to be mentioned?"  needs to be cleaned up before
>   publication!  I don't know, either.  If it were left to me, I'd have
>   to leave it in phrased as "still under investigation" or something.

+1 to something like

  OWL 2 maintains a very large degree of backward compatibility with OWL
  1.  All features of OWL 1 have been maintained, and with the same RDF
  syntax.  The core inferences of OWL 1 have been maintained, in both
  semantics, although there are some minor differences.  Some poorly
  formed OWL 1 ontologies that were in OWL 1 DL are not in OWL 2 DL.

There should then be a list describing the differences, but for this
publication it can be TBD.

> * "OWL 1 had only one profile" ...  I think of DL and Full as a
>   profiles.   

The OWL 1 DL and Full profile?  The mind boggles.  :-) 

I suggest
  OWL 1 had only one profile in the style of OWL 2 profiles.  

> * In what sense was OWL Lite "not retained"?  You can still use it.
>   Maybe better to say to say no new specification for it has been
>   provided in OWL2, but it is still usable as a subset of OWL2.

+1

> * Last paragraph (about punning) should probably have a link to more
>   details, since it's a deeply confusing concept.

How about:

Some syntactic restrictions in OWL 1 have been relaxed somewhat in OWL
2.  When exchanging OWL 1 DL ontologies, there was a very strict
separation between, for example, the names of classes and individuals.
In OWL 2 DL ontologies the same name can be used for both a class and an
individual (and also for some other combinations).  This and other
relaxations mean that the set of RDF Graphs that can be handled by
Decription Logic reasoners has become usefully larger in OWL 2 compared
to OWL 1.

> SECTION 5 Documentation Roadmap
> 
> * Let's just call it "Document" Roadmap (not "Documentation") unless
>   we're calling this the "Documentation Overview" (which isn't what we
>   decided.)

+1

> * Ummmm.  What versions are we linking to here, for this release of
>   Doc-Overview?  The Wiki?  The 2008-12-02 versions?  What about
>   Profiles, which is seriously out of date in all versions, and DRE
>   which hasn't yet been published?  I GUESS we link to the last TR,
>   except in the case of DRE, in which case we say it's to be published
>   soon, and for Profiles include text in the roadmap about it being out
>   of date.

Put a disclaimer at the beginning of the references like:

The referenced versions of documents in this reference list are in some
cases rather outdated.  The entire document set will soon be republished
as a group.  Current drafts of the documents are linked to from the [[OWL
WG home page]].

Have the Roadmap refer through the references and have direct links to
the Wiki as well.  This would become direct links to WDs later.

Something like
	[[Primer|OWL 2] Primer] [<cite>[#Primer Primer]</cite>]
to become
	[http:./Primer OWL 2 Primer] [<cite>[#Primer Primer]</cite>]

> * There's been some talk of changing the order.  The obvious things are
>   to put the non-core specs togther, before or after the user docs.  I
>   happen to like it as it is, since I think "Profiles" is more core than
>   the other non-core specs, but I wouldn't object to a change.  We
>   should probably have a WG resolution on this; I expect RPI and
>   Manchester to have strong conflicting views on this.

I'm happy with the current order.  I wouldn't mind sticking profiles as
fourth-last.

> SECTION 6 References
> 
> * I think these should be organized, somehow; right now I guess they
>   are in the order the references are made?   It ends up looking
>   pretty random.
> 
>   How about alphabetic within groups, where the
>   groups are something like:
>       OWL 1
>       OWL 2 
>       Other   (maybe divided into W3C and Non-W3C)

Alphabetising [sic] does most of this.

> * Same question as in Roadmap about which versions we refer to here.

See above.

> SECTION 7 Notes
> 
> * I don't really think an overview like this should have footnotes.
>   They don't seem overview-y.

+3

> * For Note 1 (from 2.2), this seems too detailed and novel for the
>   overview.  And it kind of seems to undermine conformance -- is
>   RDF/XML required or not?  Let's just drop this note, and address
>   this somewhere else if necessary.

+1  The primary exchange syntax for OWL 2 ontologies is RDF/XML,
    provided that RDF/XML can serialize the RDF form of the ontology.

> * For Note 2 (from 2.3), this could be inlined in 2.3, or dropped.   

+1 to just drop

> * For Note 3 (from Profiles), that could go into parentheses.


+1 to "sound and complete in many natural cases (for details see ...)."


peter

Received on Tuesday, 10 March 2009 12:16:09 UTC