Re: review of document-overview

Below some comments on the Roadmap section of the Document Overview

1. Put the Roadmap at top, as the first section of the Document Overview

2.  Roadmap

a) Add some global text for users below the Roadmap picture , something like

The OWL 2 Document Overview describes should be read before other OWL 2
documents.
The reading order of the other documents depends on the audience. Advanced
readers who are interested in technical aspects, may read the documents 2 to
5 that form the technical core of OWL 2 and 6 which describes the Profiles.
Readers familiar with OWL 1 who want an overview of the main new features
that have been added to OWL 2 and of their rationale, may read document 9.
Readers who look for a guide introducing OWL 2 and explaining how to use it
may read document 8. Ontology developers who need a  language synopsis may
use document 10. Developers interested in conformance test cases may refer
to document 10, users interested in Manchester syntax should go to document
12  (to be completed for 11 -13)

b) The link XML Serialization  is broken

c) I'd rather link to the wiki documents to prevent misundertanding or
confusions at the announcement of its publication w.r.t. LC comments

d) I suggest to remove all specific mentions at users documents like "being
revised /being completed" for the users documents, because they may be
shortly obsolete, and replace it by a single warning at top, mentionning
that all documents are under revision.

e) For QRG I'd suggest to replace the sentence : "provides an overview of
the various OWL 2 features in general" by something closer to the QRG
abstract, e.g. like "provide a quick synopsis to the OWL 2 language".

Given the schedule I don't know how to process.
I 'm available to make the changes on the wiki of those that don't raise
objection.

Christine


2009/3/10 Sandro Hawke <sandro@w3.org>

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


-- 
Christine