Re: [sca-bindings] Missing links in test case documents

[Robin Cover <robin@oasis-open.org>]

[Bryan said, in part]

> I noticed that the test case
> documents for both the WS binding and the JMS binding do not have links to
> the respective test artifacts zips files.  This means the reader really has
> no way to know these zip files exist or where to find them.

[Martin replied]
On Fri, Jan 21, 2011 at 11:08 AM, Martin Chapman
<MARTIN.CHAPMAN@oracle.com> wrote:
> Bryan,
> Good observation. I’m not sure “related work” is the right way to do this
> since the zip files are actually part of the same work product. The TC
> process does require a reference to these files without saying how! I have
> copied Robin since there was confusion over the Policy spec and he may have
> suggestions for doing this in a better way. I will also leave it to his
> judgement as to whether this would warrant a public review, since it is only
> making an implicit link explicit.
>
> Martin.

I agree with Martin's (implicit) doubt about the "right" or "best" way
to fulfill the terms of the TC Process [1] and (more importantly) to
help make readers/users aware of all essential "parts" in a
multi-part work [2].

I don't think it's wrong to use the "Related Works:" block on a
spec cover page for citation of a discrete work sub-part that
merits special attention.  This was anticipated and recommended
in the Naming Guidelines document [3] ("OASIS Naming Guidelines
Part 2: Metadata and Versioning") that's no longer the latest
reference for guidance, but was consistent with other instructions
available from the OASIS Library /templates/ area.  I think that
guidance is still applicable.

In particular, we have recommended consideration of the DCMI
relational terms in the "Related Works:" block, including
the following relations for part-whole:

hasPart:  The described resource includes the referenced
              resource either physically or logically
isPartOf: The described resource is a physical or logical
              part of the referenced resource

And so, several OASIS TCs have used  "Related Works" to reference
parts of a whole (parent to children), or sibling parts, including
"parts" that instantiate XML schemas, ontologies, and other
machine readable files or packages.

See for example, "Related Work" in the recent OASIS
OpenDocument specification:

http://docs.oasis-open.org/office/v1.2/csprd02/OpenDocument-v1.2-csprd02.html

Related Work:
This specification consists of this document as well as the
following documents, schemas and ontologies:

OpenDocument v1.2 part 1: OpenDocument Schema
OpenDocument v1.2 part 2: Recalculated Formula (OpenFormula) Format
OpenDocument v1.2 part 3: Packages
OpenDocument v1.2 Relax NG Schema (.rng)
OpenDocument v1.2 Manifest Schema  (.rng)
OpenDocument v1.2 Digital Signature Schema  (.rng)
OpenDocument v1.2 Metadata Manifest Ontology  (.owl)
OpenDocument v1.2 Package Metadata Manifest Ontology  (.owl)

I'm planning to schedule some new work to study this topic (once
the backlog of regular TC Admin support issues is handled).

Cheers,

- Robin

PS No interpretation just yet about additional public review as
possibly occasioned by the suggested change.

[1] http://www.oasis-open.org/committees/process-2010-07-28.php#quality-formalLangDefns

[with respect to] "normative computer language definitions
that are part of the Work Product, such as XML instances,
schemas... Each text file must be ***referenced from*** the Work Product..."

Ignoring the awkwardness of saying (a) that schemas are
"part of the Work Product" and that (b) they must be
"referenced from the Work Product"   -- apparently requiring that
the latter use mean "from the relevant prose part(s) of the
the Work Product, more immediately visible than the non-prose
parts of the Work Product -- it's not clear by what means the
CLDs are to be "referenced from" the (prose part(s) of) the Work
product.

TCs do want more guidance.  In the previous [pre-October-15]
version of the Naming Guidelines, some discussion was
presented about non-prose artifacts that are parts of multi-part
works, but this content was not brought forward, and needs to be
reworked in a Naming Directives document update, and maybe
in spec templates.

[2] http://www.oasis-open.org/committees/process-2010-07-28.php#quality-multiPart

[3] http://docs.oasis-open.org/specGuidelines/namingGuidelines/metadata.html#relatedWork

Excerpt:

"Within a prose specification title "page", TC editors should
supply the title and applicable URI for any other resource
closely associated with the specification, where reference to
the related resource is deemed essential or strongly motivated.
In most cases, the TC editors are to make a judgment,
necessarily subjective, as to whether a Related Work reference
would be of significant benefit to the human reader.

Informally (not with an intent to formally implement DCMI
metadata models), OASIS TC editors may wish to study the
collection of Dublin Core Metadata Initiative (DCMI) terms
defined as element refinements of DCMI relation
[label Relation] --- as these may prompt ideas for Related
Work candidate references. In DCMI, a relation stores
"a reference to a related resource... Recommended best
practice is to reference the resource by means of a string
or number conforming to a formal identification system."
Here are some of the element refinements build from DCMI
relation, usually reciprocal...

>
>
>
> From: Bryan Aupperle [mailto:aupperle@us.ibm.com]
> Sent: 21 January 2011 15:05
> To: sca-bindings@lists.oasis-open.org
> Subject: [sca-bindings] Missing links in test case documents
>
>
>
> I bring this up somewhat reluctantly since it could force additional 15-day
> public reviews.
>
> While researching an issue in the Java TC, I noticed that the test case
> documents for both the WS binding and the JMS binding do not have links to
> the respective test artifacts zips files.  This means the reader really has
> no way to know these zip files exist or where to find them.
>
> The assembly and policy test case documents have links in the Related Work
> section of the front matter.  For example, from the assembly document:
>
> The Test Suite artifacts relating to this document can be found here:
> http://docs.oasis-open.org/opencsa/sca-assembly/sca-assembly-1.1-testcases-cd03.zip
>
> We probably should add these links.
>
> Bryan Aupperle, Ph.D.
> STSM, WebSphere Enterprise Platform Software Solution Architect
> WW Center of Excellence for Enterprise Systems & Banking Center of
> Excellence Application Integration Architect
>
> Research Triangle Park,  NC
> +1 919-254-7508 (T/L 444-7508)
> Internet Address: aupperle@us.ibm.com



-- 
Robin Cover
OASIS, Director of Information Services
Editor, Cover Pages and XML Daily Newslink
Email: robin@oasis-open.org
Staff bio: http://www.oasis-open.org/who/staff.php#cover
Cover Pages: http://xml.coverpages.org/
Newsletter: http://xml.coverpages.org/newsletterArchive.html
Tel: +1 972-296-1783