[www-qa] A good example of documenting for testability

If you've been reading the W3C documents about QA, especially
http://www.w3.org/2001/01/qa-ws/slides/qacirc.jpg
(the concentric circles), know that an early focus will be on the
documentation from which test suites are derived. The Recommendations
and other normative documents must prefer explicit statements over
silence, and we have a good example at hand.

I was just browsing through the Functions & Operators draft at
http://www.w3.org/TR/xquery-operators
and found this interesting issue on the issues list:

<quote>
Issue 45: Collations: Is there a relationship to xml:lang?
(operator-collation-relation-to-lang)
Originator: Michael Sperberg-McQueen
Locus: Syntax
Description: The relation of collation-sequence selection to xml:lang
labeling of the data needs to be addressed explicitly, even if there is
none. (Steve Zilles suggested that since nothing was said about getting
defaults from xml:lang values, it was clear that xml:lang does not affect
the selection of collation sequences. But earlier, people had said an
implementation was clearly free to take a default-collation value from
the user's locale, if one was available, on the grounds that nothing was
said about it and thus nothing prevents it. We can't argue both that
silence in the discussion allows implementors to do anything they like as
regards the user's locale, and that it requires implementors to do
nothing as regards xml:lang.

So I argue that if we want there to be no interaction with xml:lang, or
if we want such an interaction to be legal but not required, or if we
want it to be required, we ought to say explicitly what we want.
</quote>

We need to encourage the idea that external/environmental factors must
be addressed whenever they may result in variations of operation of
the software. In this example, consider how one would test sorting.
Can a test author provide one worldwide standard for a correctly
sorted result, or must the test harness check parameters of the
environment and choose/generate a reference output to be matched? In
the "legal but not required" scenario, the software developer must
inform the world about whether they check the environment or not, and
that bit of information must be fed into the test harness. It all
starts with good documentation.
.................David Marston

Received on Friday, 7 September 2001 15:38:52 UTC