RE: [tag-comment] Make 2.1-2.2 less abrupt for the reader

["Durand, Jacques R." <JDurand@us.fujitsu.com>]

David:

Indeed, section 2.2 seems to have been pasted hastily between 2.1 and
2.3, and breaks the flow. I suggested something close to your comment
below (see my "issue 053" in a recent mail).
We need to seriously revisit 2.2. which may also have some overlap
issues that it didn't have at the time it was written.

Jacques

-----Original Message-----
From: david_marston@us.ibm.com [mailto:david_marston@us.ibm.com] 
Sent: Monday, February 18, 2008 1:39 PM
To: tag-comment@lists.oasis-open.org
Subject: [tag-comment] Make 2.1-2.2 less abrupt for the reader

One of the big potential objections to writing TAs is that it amounts to
asking a TC (or WG) to write the spec twice. I don't claim to have a
solution for that issue, but I have some suggestions about how the early
parts of chapter 2 could flow in a reasonable manner for the reader who
is skeptical about TAs. As I heard in the 6 February call, the idea of
swapping 2.1 and 2.2 is open to discussion and may help. Please look
over this arrangement and see what you think.

Assumption: 1.1 has an adequate discussion of TAs contrasted to test
case meta-data, and that chapter 1 as a whole has asserted that TAs
aren't simply a matter of "highlighting" certain sentences in a prose
specification. The skeptical reader has read in 1.2 that there are
benefits to TAs, but may still be skeptical. Then they read on to
chapter 2....

====================== BEGIN REVISION ============================ [NEW
material in 2 before 2.1 heading] As stated in 1.2, TAs need not be
authored by the same people who are writing the prose of the
specification. However, TAs come from the same body of ideas and may be
considered a reduced and formalized expression of the specification's
ideas, or at least those ideas that will eventually be embodied in a
test regime. Each TA is one idea about measuring the behavior or
properties of an implementation of the spec.

Since the reader is likely familiar with specifications of the type
issued by OASIS and others, and since most such specifications do not
currently have TAs, most of the examples show how TAs are derived when
specification text was written first. But note that TAs could be written
first, as a set of formal rules for implementations, and then the
specification text could be derived.

[Rearranged material for 2.1 and 2.2]
Section 2.1: Creating TAs
[2.2 materials about atomicity]
A test assertion should...[4 bullets]...
[2.2 widget example]
Although it would be acceptable for assertion #2 to be a literal...
Note that writing an assertion results in a bold statement...
[another 2.2 paragraph moved up from deeper down] There are different
objectives for test assertions...
[New]
One use of TAs, which will be of special interest to OASIS TCs and other
spec writers, is to distinguish conformant implementations from
non-conformant ones. TAs can also express a formalism for obtaining an
implementation-defined property which will be the basis for other TAs or
other wording in the specification text; see part 2.4 for more on this
topic.
[Back to material from 2.2]
Do not change the semantics of the specification...
A link between test assertion abstract descriptions...
[Testability subsection from 2.2]
[The last piece of 2.2 stays in 2.2, as shown below.]

Section 2.2: Minimal Components of a TA
[former 2.1 materials]
A test assertion must always:...[4 bullets]...
[2.1 widget example]
[Observation #1]
[New]
TAs don't express the optionality. When you apply a test derived from a
TA, you only obtain the factoid that the IUT has or does not have the
property/behavior being tested. In the above example, the property is
whether the item is rectangular. The consequence of that factoid is
outside the scope of the TA.
[Back to material from 2.1]
In an actual test assertion definition,...
Note: in many cases, there is no need to use a sophisticated...
[old 2.2 material about common terms]
Common terms, items and details may occur in several assertions...
[Then continue with 2.3 and onward as in the current draft.]
====================== END REVISION ============================

In the above, the four elements that are "always" present in a TA
(though they may be inferred) are not introduced until after the reader
has a stronger sense of what a single TA is like. I would also hope that
chapter 4 is clear about all the structural parts of a single TA that
TAG will define, and identifies extensibility points. An XML notation
would have great explanatory power there.
.................David Marston