Proposal for SpecGL Guideline 8, mostly about 8.4

Specification Guidelines [1] has last call issues 16 and 39, which both
essentially say that the checkpoint 8.4 is too mushy regarding the kind
of consistency it is intending to promote. After some email interchange
with Lofton Henderson and Dominique Hazaël-Massieux, I propose the
following set of changes to Guideline 8 as a whole. The changes ensure
that points that QAWG wants addressed get addressed somewhere, while
clearing away extraneous material from Ckp 8.4. Steps A-F below should
be evaluated as an integrated proposal.

A. 8.4 will be clearly more general than 8.3, so I propose swapping the
two. In the rest of this message, the old numbers will continue to be
used.

B. Being able to find all discretionary items from one starting point
is very desirable, but that's a documentation criterion discussed in a
different guideline. Accordingly, I propose that the sentence in Ckp
13.4 that starts "In addition to the minimal required set above, other
conformance related information such as..." should be expanded to
mention complete lists of all deprecated features, discretionaries, and
extension points. (Treatment of CoP, modules, levels, and profiles when
there is a fixed list would come under a more stringent policy, IMHO.)

C. Clarify the conformance requirements of 8.1 by editorially revising
the words "and MUST identify by labeling all discretionary items" to
"and MUST identify all discretionary items using the *terminology of
this guideline* or equivalent words, used consistently and distinctively
to mean discretionary." Add a "Rationale: test creators will want to
discover all choices and variability allowed to implementers. Having a
name for each discretionary item, and a link target for each one, allows
systematic reference to individual items from test cases as well as
elsewhere in the specifications." (Historical note: DM, DHM, and LH did
not agree on the interpretation of the existing verbiage.) The * shows
where there could be a link to the "3 variants" part of the guideline.

D. Add a paragraph to 8.3 that says: "It is possible for a discretionary
item to affect the range of available options on another item, or to
render it moot. For example, if a discretionary choice addresses
serialization of characters as entities, one option of that choice may
render moot a grant of discretion regarding entity names for character
entities."

E. Take one of the potentially confusing alternate interpretations out
of 8.4 by adding another paragraph to 8.3: "Names of discretionary
items, and names of choices if used, should use verbiage consistently
in order to satisfy Checkpoint 13.3[link]. Identical words should be
used for identical behaviors." Possibly add complementary verbiage to
13.3, which might also encourage consistent verbiage for deprecation
and extensions.

Steps B-E pluck away sources of confusion, allowing a cleaner 8.4....

F. (Finally) Overhaul 8.4 into the following:
===============================================
Checkpoint 8.4. Promote consistency across multiple discretionary items.
[Priority 2]

Conformance requirements: the specification MUST indicate the rationale
for discretionary items being separate rather than consolidated. This
requirement is not applicable for specifications that do not have
discretionary items, or have only one discretionary item.

Rationale: the use cases begin the process of setting expectations of
how implementations will be used. When further refined, the use cases
set expectations for variation or flexibility of implementations. Any
variability that is too detailed for the use cases is probably of low
value to the user, but it hurts interoperability. (See [link to excess
DoV paragraph].) When individual details are subject to discretion but
can be summarized as a policy-level decision, the specification MUST
present one named discretionary item for the policy OR present a
justification for dividing the item into smaller items. When one item
affects more than one feature, the specification of each such feature
SHOULD refer to the discretionary item by name and link to the place
where the item is explained generally.

When a rationale exists for dividing a discretionary item that could be
consolidated, the rationale MUST cite benefits to the user and/or an
existing division over which the Working Group has no control. It may
present other reasons as well. Also, the related items should be
consistent in their range of options and their use of terminology.
(Consistent terminology is required to satisfy Checkpoint 13.3[link].)

Specifications SHOULD propagate rules for consistent terminology about
discretionary items onto the implementations, especially when an
implementation could offer choices to the user. Where an implementation
may exercise allowed discretion by adapting to the environment in which
it is run, specifications SHOULD encourage the implementation and any
associated documentation to use the specification's terminology.
===============================================

Observation: I think the weakness of the earlier rationale was its
derivation from abstract concepts of goodness, so I changed it to one
driven by use cases, which strikes me as the existing WG task that best
separates user benefit from user confusion and hassle.

I want to state once again that 8.4, as formulated above, is very
important to conformance testing. I have written about the problems of
discretionary items in a journal article [2] and other places.
.................David Marston

[1] http://www.w3.org/TR/qaframe-spec/
[2] http://mitpress.mit.edu/catalog/item/default.asp?ttype=6&tid=7992

Received on Friday, 25 April 2003 15:52:12 UTC