Re: review of document-overview

Sandro Hawke wrote:
> 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.

+1. The generic template breaks down for that one:-(

> 
> * I think the title should be
> 
>      OWL 2 Web Ontology Language
>      Part 1: Document Overview
> 

+1. We indeed agreed on that.

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

Heh. +1 due to W3C's rules. I let you discuss the anglo-american issues
with Ian in a dark alley somewhere:-)

As an aside: somebody really aware of the differences may have to go
through the other documents, too. I know I tend to use UK spelling
because that is what I learned at school but, then, with so much
American around me I simply got completely confused and I probably use a
mixture of the two:-(

> * 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
> 
> * "At the bottom are the two semantic specifications"
>                                                     ^ discussion in
>                                                     seciton 2.3
> 
>    (without these forward references, the diagram is unexpectedly
>    baffling, I think)
> 

+1

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

The original source is in Adobe Illustrator. Setting the size is easy,
because I generate the image from the SVG dump via batik. I presume that
by coulours you mean separating, eg, the syntax and the semantics into
different colours? I am happy doing that. (Let us discuss that off line)

> 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 for structures

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

:-)

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

Hm. +0.5:-)


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

Actually... There is the issue of those RDF graphs, using the OWL
vocabulary, that are not mappable to the structure. We might want to
define OWL Full to be the part that _is_ mappable. I am not sure, though...

But if we do not want to go there, then I agree. +1


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

0 :-)

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

+1

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

I am afraid of the possible discussion around this, with communities
clashing (again). RDFS-Fast? Is that correct with, formally, an infinite
number of terms? The OWL 2 Full + Direct Semantics is, formally,
defined, just non tractable? Not sure for these, I must admit.


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

+1 to the whole, I must admit that I more or less made a copy paste for
this chapter. You had somewhere a much better characterization of
Profiles and I would be happy to use that instead of what is in the text
right now.

> 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

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

+1

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

My mistake. +1

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

+1 for the wrong link (sorry!). I am not sure what else you would put
there in terms of the description, though...

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

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

Well, if we follow that line overall in OWL 2 then you are right.

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

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

Yes

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

0

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

This refers to an item above... It depends a bit how we formulate this.
If this is the _only_ footnote than we should indeed drop it.

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

+1

Thanks!

Ivan

-- 

Ivan Herman, W3C Semantic Web Activity Lead
Home: http://www.w3.org/People/Ivan/
mobile: +31-641044153
PGP Key: http://www.ivan-herman.net/pgpkey.html
FOAF: http://www.ivan-herman.net/foaf.rdf