RE: [ubl-cmsc] [Fwd: Some comments on the Guidelines for Schema Customiz

Subject: RE: [ubl-cmsc] [Fwd: Some comments on the Guidelines for Schema Customizations]

People

we've just received these comments (erroneously sent to a different SC);
given the last minute timing of the comments I'm not sure how we'll be
able to deal with them for 1.0, although we certainly should do our utmost to
take them into consideration...

I have sent a query to Jon as to how much time we have; I guess what we do
will depend on his response.

-------- Original Message --------
Subject:        Some comments on the Guidelines for Schema Customizations
Date: Thu, 08 Apr 2004 13:05:33 -0700
From: Ray Seddigh <RaySeddigh100@yahoo.com>
Reply-To:       RaySeddigh100@yahoo.com
Organization: Ray Seddigh
To:     Eduardo Gutentag <Eduardo.Gutentag@Sun.COM>, Anne Hendry
<Anne.Hendry@Sun.COM>
CC:     ubl-ttsc@lists.oasis-open.org, Fabio.Arciniegas@postgraphy.com

Hi all,

I had the opportunity to read this well-written Guidelines document (The
UBL context methodology paper - _Guidelines for the Customizations of
UBL v1.0 Schemas -Working Draft 1.0-beta3, 4/29/04_).

I enjoyed the thorough coverage of the document, and its elegant balance
of explication and concision.

In response to requests for comments, below are some preliminary
observations.

Attached is an Open Office file version of these comments. For
completeness of reference, also attached is that particular version of
the original Guidelines document on which my comments are based.

Hope this helps.

Best,

Ray Seddigh
__________________________________________________

*Some Comments on the UBL Schema Customization Guidelines Document
*Ray Seddigh*
*

*
In these comments*

The focus is mostly on what a reader might expect from the document, a
few additional aspects of customization, further clarity of exposition
particularly for the many upcoming newcomers to UBL. A few stylistic and
copy-editing points are included peripherally, at the end.

*Not in these comments*

Expanded ideas about the relationships of tools, applications, and
context methodology are not included here, but reserved for a focused
discussion/document on such relationships.

*General
*

Mechanisms for sharing, exchanging, and collaborative evolution of
customized libraries.

As customized libraries are created using the guidelines of the paper,
quite often they will inevitably need to be shared, combined, or
collaboratively augmented. This need can arise within organizational
boundaries, across them, or both. The paper is silent or implicit on the
mechanisms for addressing this eventuality. More direct explanation
would be useful here. If there are existing methods, or implied models,
then those approaches could be referred to.

There are pragmatic considerations as well. For example, are there any
coordination, storage, or registry requirements in order to make
elements of disparate customized libraries work together? If there are
none or if this topic will be addressed in the future, it helps to state
the same. Are namespaces the only apparatus needed?

If there are coordination, storage, or registry requirements, are they
centralized or distributed? Most importantly, what should the customizer
understand, or do, as they customize, in order to account for these
mechanisms (or plan for them if they are to be developed in the future)?

Audience-

In the preambulations of the document, it would help to mention to whom
this document is of use and addressed. e.g.

Types of individuals (Application developer, manager, standards
developer, customizer ...)

Communities of interest / types of organizations: Industry groups,
standards groups, software vendors, government organizations, ...

CCTS treatment - lines 61- 63 (Introduction)

While reference is made to the CCTS via a link, a brief one paragraph
outline of CCTS would make the document more self-contained and easier
to follow. A simple diagram depicting the architectural relationship of
UBL and CCTS would add even more clarity.

Line 72 – Interoperability

Due to the numerous connotations of "interoperability", it would help to
disambiguate by indicating which notion of interoperability is intended
here and elsewhere (interoperability among what and what?).

Interoperability among UBL systems and EDI systems?

Among trading partners using customized and non-customized UBL documents?

...

Lines 90-93

Could be rewritten for clarity.

Lines 108-111 - Escape mechanisms

While escape mechanisms can be inferred, they could be specifically
described or listed.
A brief example would reduce the chance of misinference.

Lines 118-120

“This document does not provide instructions or how to incorporate UBL
schemas into other XML-based standards at the semantic level.” Would
this, or an equivalent paraphrase be useful? Note this is somewhat
distinct, although overlapping with “customization for other industries”
point.

Line 164

Interoperability among ...?

Line 306 - Context drivers

A one line description of the “Business Process” context driver would be
useful here.

The same applies to context drivers that follow, but the first (Business
Process) is a central one, making it more useful to have a brief
description.

Lines 339-348

The method for describing custom context drivers is illustrated here.
However, the method for naming such a custom context driver is not. Does
each customized context driver have a unique id (aside form a long prose
description) so that it can be distinguished from other customized
context drivers? Can context drivers be assigned
pointers/handles/variables such that they can be referenced inside code
or data without the need to mention a long prose description?

Perhaps this is within the purview of NDR documents. Nonetheless the
reader can only be helped by the brief clarification of these points
without having to refer to other docs.

Line 354 – Codelists

A brief definition and / or example of codelists and their overall role
in UBL would provide for a useful transition to this line, and show the
relevance.

Line 353 vs. line 364

listID and listURI – perhaps these can be further disambiguated to avoid
likely confusion of the two. May be an example can accomplish this.

Line 370 – Context chains.

The two concepts of context hierarchy and “given hierarchical level in
that context” are referred to here, and implicit in what follows, but
they are not defined. Their relationship to “context chains” could be
clearer. Are they the same? If so one could use the same name. If not,
could one expand on the distinction? A brief definition or a recap (not
a reference to another document) would provide for a smoother read.

Line 389

Doesn't the “no constraint” about namespace name apply to restrictions
as well as to extensions? (BTW typo on line 389: not constraint => no
constraint).

Lines 488 – 500

Generally, this section is likely to appear inscrutable to those new to
UBL. There are quite a number of references to new, undefined (in this
paper) topics, acronyms, and names of constructs. Appears as an
enumeration of concepts versus an expository rendition of how these
concepts relate to each other, to context methodology, to the UBL type
library, and the needs of the customizer. Are all these references
central to the goals of this paper? If so, perhaps a rewrite of these
lines along with an example would make for a clearer read. As an aside,
stylistically, it may help to make some of the sentences in this section
shorter.

Also, for better legibility, one could place the related NDR picture
in-line here, vs. making a reference to it.

Line 507 schema modules

A one line description of a schema module here would help differentiate
it from other neighboring concepts mentioned in this paper.

Line 508 extension, refinement

“before extending or refining” --- The distinctions between refinement,
extension, restriction and narrowing would be useful to mention
somewhere early in the document.

Line 513

Anaphora resolution – which namespace does “that namespace” refer to?

*Minor Typos and Copy editing*

Lines 283-299

These lines seem to be a verbatim repeat of lines 227-241. If emphasis
is the goal, perhaps a paraphrase or summary would avoid the duplication
of the paragraphs.

Line 67 "lessons"

Line 78 "mechanism that took a standard"

Line 92 "all possible values of it" ?

--
Eduardo Gutentag               |         e-mail: eduardo.gutentag@Sun.COM
Web Technologies and Standards |         Phone: +1 510 550 4616 x31442
Sun Microsystems Inc.          |         W3C AC Rep / OASIS BoD

ubl-cmsc message