issues with the Usage Guide to be resolved before publication

Hi Rama and Brahmananda,

here is a list of things that need to be fixed in the Usage Guide before
I think it can be published. They will be discussed in our telcon
shortly.

1) fix all the annotation URIs:
there are the following types of problems:
   a) using domain names like owl-ontologies.com, mynamespace.com - 
      we absolutely cannot use such domains, instead we have our w3.org
      spec URIs and example.com and similar.
   b) writing a URI like "www.w3.org/..." which misses "http://" - 
      e.g. in listing 3.2-2
   c) writing a URI like "schemaMappingNS#OrderRequest.xslt" seems to 
      intend to identify a file OrderRequest.xslt but misplaces the name
      in fragment ID
   d) writing URIs like "SampleOntology#UPC" to point to something that 
      is elsewhere defined as 
      "http://www.mynamespace.com/SampleOntology.owl#UPC"
   e) similarly, writing URIs like 
      http://example.org/categorization/PurchaseOrderServices/ItemAvailability 
      to point to something that is elsewhere defined as 
      http://www.owl-ontologies.com/unnamed.owl#ItemAvailabilityCheck
   f) unhelpful URIs like http://www.owl-ontologies.com/unnamed.owl#
      should be avoided
   g) using relative URIs without specifying the base - instead you can 
      use entity references or full URIs which won't be so long anyway 
      after we publish

2) put listing captions before the listings. Listings flow with the text
so they are not viewed as a block and the user usually sees the caption
only after reading the whole listing.

3) rename 2.a and 2.b to 2.1 and 2.2 (renumbering the current 2.1) - as
it is, the two first subsections of 2 (a and b) are not well
distinguished

4) complete listing 3.1-3 - the ontology also defines classes
DeliveryDate, Quantity and AvailabilityConfirmation, according to the
URIs that are used in listing 3.1-2.

5) add an editor's note or TODO in section 3.2 that the listings
currently use URIs from a single ontology (SampleOntology) but should
use URIs from two ontologies (as the text implies), and a mapping
ontology is available that ties those two together (that's because the
mapping ontology won't change the URIs of the things mapped).

6) fix the formatting of listings 3.2-3 and 4-3, in the latter just drop
the XML declaration (and the same elsewhere if other XML snippets have
it)

7) add an editor's note or TODO in section 3.3 that it shall be merged
with section 3.4 - the bulk of what is in section 3.4 belongs in the now
very short 3.3, and then 3.4 would only say that techniques from 3.2 and
3.3 can be used together (combining subClass reasoning with
composition), which can be a note at the end of 3.3.

8) in listing 3.4-2, add a modelReference on the WSDL operation that
says the operation does translation, something like:
modelReference="http://example.com/utilities#translation" 
and say in the text that this will let the composer know that this
function does the translation and can be put in the correct place in the
composition

9) drop paragraph after listing 3.5-1 and the listing 3.5-2 - the text
and the listing seem to indicate that ontology terms can be inferred
reliably from the names of XML elements, which is not what we want to
imply, I'd say. Instead we can say something like this:

"If a requesting WSDL is annotating with multiple concepts like shown in
listing 3.5-1, this increases the number of matching service WSDLs, and
similarly if a service WSDL is annotated with multiple concepts, more
request WSDLs will match it."

10) drop the last sentence from the paragraph after listing 3.6-1 - 
I don't think we talk about behavioral aspects of parameters - we only
talk about behavioral aspects of operations or interfaces in SAWSDL.

11) add an editor's note or TODO in section 4 that the current leading
text will be rewritten - it is all from a perspective of discovery, not
invocation. The text should really talk about XML messages going to and
from the service, and schemaMapping them from and to semantic data on
the client, that can also be obtained by symetrically mapping the
client's XML data using schemaMappings.

12) add an editor's note or TODO around listing 4-3 that the XSLT, as it
is, does not work, and that it will be completed.

As I said, we will discuss these points in the telcon when we discuss
what needs to be done before we can publish the first public working
draft of the usage guide, so there will be space for disagreement or
clarifications.

Hope this helps,

Jacek

Received on Tuesday, 26 September 2006 15:37:08 UTC