per-Framework glossary sections

Feedback/discussion invited...

The Issue
-----

In QAWG teleconference discussion, I was given an action item to start a 
wider discussion about one contentious aspect of QAWG Issue 19 [1].  Issue 
19 concerns definition/glossary sections in individual Framework documents 
-- Specification Guidelines (SpecGL), Operational Guidelines (OpsGL), 
etc.  The aspect in dispute is:  what sorts of definitions should be in 
them, and how should such definitions relate to the central QA Glossary [2].

I will both described the issue, as well as present and argue for a 
position (proposal) on it.

Background
-----

Issue 19 was closed at one point.  The current (pre-reopen) resolution of 
Issue 19 is:  "each Framework part may have a definitions section, to be 
decided as needed on a case-by-case basis, to supplement and not contradict 
any existing QA Glossary definition."

There has been some unhappiness with the last part -- definitions may 
supplement and add information that is exemplary or helpful in the context 
of the specific Framework document.  Therefore QAWG agreed to consider 
arguments to revise this part of the earlier resolution (or not).

UAAG represents one model, on which the current resolution of Issue 19 is 
based.  The UAAG glossary chapter [3] contains terms that are in some cases 
defined in a terse and unqualified way (e.g., applet), and others that 
contain significant context-related explanation, examples, etc (e.g., 
assistive technology).

By contrast, the central QA Glossary [2] has definitions that tend towards 
the terse, and by the nature of being in a central glossary, contain only 
information that is generally applicable regardless of context.  I.e., the 
central definition has to be equally applicable to the contexts of 
different GL documents (SpecGL, OpsGL, and TestGL).

While the related resolved Issue 65 does not require that the level of 
detail in QA Glossary terms be minimal --i.e., terseness is not mandated -- 
nevertheless since QA Glossary is the home of the central generic 
definitions, context-specific detail is not appropriate.

Proposal
-----

To focus discussion, here is a specific proposal (more or less the current 
issue resolution).

The key components of a solution should be as in the bullet list of Issue 
19.  For each term in the Definitions chapter:

     * if term is in QA Glossary, point to that in its definition;
     * (optionally) supplement the QA Glossary definition with exemplary 
material, explanation or extension in particular GL document context, etc

Points that are not under dispute in the re-opening of the issue include, 
for the Definitions chapter as a whole:

     * call it a "Definitions" section (avoid confusion with QA Glossary);
     * initial verbiage in the Definitions section explains the section's 
relationship to QA Glossary;

Arguments
-----

In arguing for the Proposal, I'll use the example of "test assertion" 
(TA).  From the QA Glossary [2]:  "A set of premises that are known to be 
true by definition in the spec."

I maintain that this is not very useful to someone who is trying to 
interpret the requirements of SpecGL (or TestGL or OpsGL, for that 
matter).  What is a test assertion? What does one look like?  How do you 
know if a specification satisfies SpecGL TA-related checkpoints of 
Guideline 14 (GL14), "Provide test assertions."?

The definition in the SpecGL Definitions chapter is better, but should 
still be enhanced with more material and brief illustrations (and has a 
couple of known flaws).  The SpecGL definition is:  "any sentence or 
equivalent assemblage of words and phrases that prescribes the behavior 
that must be obtained when a stimulus occurs under a certain set of 
conditions. (See also QA Glossary [QA-GLOSSARY].)"

It has been counter-argued that it suffices to have additional explanatory 
text *somewhere* in SpecGL (but not in the Definitions section), or in the 
companion Spec Examples & Techniques.  IMO that does not suffice, and here 
are three actual examples (related to "test assertion"):

1.) In one teleconference, we (QAWG) argued for some while about some 
aspect of "test assertion" nature without realizing that what we were 
discussing was actually already defined in an obscure corner of the 
text.  (IMO, that bit should have been replicated in "Definitions").

2.) In a recent teleconference -- while discussing the test assertions of 
SpecGL itself -- we realized that we (QAWG) do not even agree on a 
practical working definition of "test assertion" -- i.e., what it takes to 
satisfy SpecGL's requirements.  This disagreement had lurked for many weeks 
but we didn't realize it because we hadn't tried to write down an actual 
working definition.  (Here is one place where I think the current SpecGL 
definition is still deficient.)

3.) When editing SpecGL for a few months, sometimes I myself could not 
easily find where SpecGL gave the useful contextual definition about a term 
or concept.  I wanted it to be in one central place, a Definitions 
section.  If the authors have trouble finding needed details, what about 
the casual reader?

This represents wasted time.  It does not indicate a user-friendly 
document.  It could be more so, with UAAG-like Definitions section, without 
diluting or obscuring the essential conformance requirements.  When I was 
first working with UAAG (and other WAI documents), I came back to the 
glossary sections repeatedly -- they were an invaluable aid to 
comprehending the document.

Feedback
-----

Other thoughts?

Regards,
-Lofton.

[1] http://www.w3.org/QA/WG/qawg-issues-html.html#x19
[2] http://www.w3.org/QA/glossary
[3] http://www.w3.org/TR/2002/REC-UAAG10-20021217/glossary.html#terms