review of document-overview

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.

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

SECTION 1

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

  "W3C uses U.S. English (e.g., "standardise" should read
  "standardize" and "behaviour" should read "behavior")."  --
  http://www.w3.org/2001/06/manual/#Spelling

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

SECTION 2 (Overview)

* "At the top are various concrete syntaxes that can be used to"
                                           ^ discussed in section 2.2

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

   (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?

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.

SECTION 2.2 Syntax

* "serialisation" (UK spelling)

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

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.

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

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

* 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.

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.

* 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).

* 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.

* 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.

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)

* 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.

* 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...

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

* 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.

* "OWL 1 had only one profile" ...  I think of DL and Full as a
  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.

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

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.)

* 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.

* 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.

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)

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

SECTION 7 Notes

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

* 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.

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

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

Received on Tuesday, 10 March 2009 04:13:45 UTC