OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.

 


Help: OASIS Mailing Lists Help | MarkMail Help

cti message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]


Subject: Document design issues for Multi-Part Work Products


CTI TC Members,

I'm providing below some additional explanation about Multi-Part Work Products (to supplement the recent message from Chet Ensign on "Options for organizing your specifications").

The details below relate especially to the composition, naming, and versioning of "Parts" in a Multi-Part Work Product (MPWP), as may be relevant in your design discussions for refactoring the transitioned STIX/TAXII/CybOX content. Most explanations are presented in the Naming Directives policy, per references below [1] - [3].

Note: All OASIS Work Products are multi-part in the trivial sense of having multiple files (as storage objects): an(X)HTML representation with at least one image logo file, and a PDF for paper-print display.  In this note, "Multi-Part" refers to the more common usage.  We use the term "Multi-Part" to refer to a Work Product that has distinct, independently (separately) titled prose "parts", not just multiple files   Most OASIS Work Products also have machine-readable files in addition to the prose parts (sometimes hundreds or thousands), and all constituent files are "parts" of the WP, even when the WP is not constructed as a "Multi-Part Work Product" with independently / separately  titled prose parts.

Constructing a Work Product as Multi-Part provides a great deal of flexibility in how conformance clauses, XML namespaces, machine-readable (file) components, and other variable content can be formulated and organized.   See examples below [6].  OASIS Staff can review any candidate/proposed design, but so long as the Work Product as a whole fulfills the template requirements for required sections and other features, any natural hierarchical design can likely be supported.   Of course: an OASIS Technical Committee can define any number of Single Part or Multi-Part Work Products that reference each other.

Composing a Work Product as Multi-Part does mean the MPWP is progressed along the maturity/approval path as a whole; even if no substantive changes are made to one or more parts for a given release.  The whole thing -- with all constituent parts (and files) -- is subject to any motion or approval action via Work Product Ballot [5].  The constituent prose parts (and their associated machine-readable files) can evolve at different rates, of course.  Revision work is done by TC members at Working Draft level, however, where incremental changes are not subject to an official Work Product Ballot, so official TC (or Subcommittee) approval actions as presented in TC Process are not involved.

Not all TC members deed to grok the details about Multi-Part Work Product composition and naming, but the technical leads will probably want to become familiar with the Naming Directives document.  Please let me know if I can answer questions at any time about these topics.

Cheers,

- Robin Cover

[1]  Naming Directives: 7. Work Product Title/Name and Acronym
http://docs.oasis-open.org/specGuidelines/ndr/namingDirectives.html#WorkProduct-Title

"This section provides guidance on creating human-readable names for Work Products, including variations needed for the name/title of separately-titled prose "parts" in a Multi-Part Work Product. The variations for title construction are parallel to naming variations in Multi-Part works for filenames and paths/URIs..."

[2] Path Components in Document URIs: Multi-Part Work Products
http://docs.oasis-open.org/specGuidelines/ndr/namingDirectives.html#URIs-MP

[3] Filename for a distinct separately-titled prose part of a Multi-Part Work Product
http://docs.oasis-open.org/specGuidelines/ndr/namingDirectives.html#filenameSyntaxMP

[4] TC Process: Multi-Part Work Products
https://www.oasis-open.org/policies-guidelines/tc-process#quality-multiPart

"(Subsection 5) Multi-Part Work Products. A Work Product may be composed of any number of files of different types, though any such multi-part Work Product must have a single Work Product name and version number. Irrespective of the number and status of the constituent parts, the Work Product as a whole must be approved by a single Work Product Ballot."

[5] Work Product Ballot
On approval actions matching the definition of Work Product Ballot, see:
https://www.oasis-open.org/policies-guidelines/tc-process#dWPballot 

[6] Examples of OASIS Multi-Part-Work Products

* Note that in some cases (pre-2012), details may vary from current naming rules; for example, the first prose "Part" is "Part 1".

OData Version 4.0 Part 1: Protocol
http://docs.oasis-open.org/odata/odata/v4.0/os/part1-protocol/odata-v4.0-os-part1-protocol.html

Akoma Ntoso Version 1.0 Part 1: XML Vocabulary
http://docs.oasis-open.org/legaldocml/akn-core/v1.0/akn-core-v1.0-part1-vocabulary.html

Open Document Format for Office Applications (OpenDocument) Version 1.2
http://docs.oasis-open.org/office/v1.2/os/OpenDocument-v1.2-os.html

searchRetrieve: Part 0. Overview Version 1.0
http://docs.oasis-open.org/search-ws/searchRetrieve/v1.0/os/part0-overview/searchRetrieve-v1.0-os-part0-overview.html

--
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/people/staff/robin-cover
Cover Pages: http://xml.coverpages.org/
Newsletter: http://xml.coverpages.org/newsletterArchive.html
Tel: +1 972-296-1783


[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]