Re: Proposals for next iteration of Test Assertion Markup Language, etc

[Stephen Green <stephen.green@documentengineeringservices.com>]

I jumped in somewhat and updated those documents (0.6).
Of course we have yet to discuss the content.

I updated the wiki to add a page on public review comments
(just Ken's) in addition to the page on the private review
comments.

Maybe we need another for the internal comments.

Here I've attached a quick text file of the external comments
with a section to add a disposition to each comment.

If we add the dispositions when they are agreed we can post
this or other such document to the documents section in the
TC web site. (We can point to this in the wiki.)

Since we addressed most of the issues from the private review
prior to the release, our internal comments may the source of
most changes.
---
Stephen D Green




2009/9/14 Stephen Green <stephengreenubl@gmail.com>:
> I've a few things I'd like to include in another iteration (perhaps after
> tomorrow's meeting):
>
> 1. add 'interpretation' and 'comment' (like we have in normativeSource)
>    to 'predicate', 'prerequisite' and 'target'
>
>    see http://lists.oasis-open.org/archives/tag/200909/msg00015.html
>
> 2. tidy up the Test Assertions Part 2 spec - correcting typos and some
>    of the normative language (there are still a few 'MUST's instead of
>    'shall's
>
> Note: I still need some convincing of a structure where an *attribute*
> value determines whether a TA set shared part overrides or adds to
> the set's TAs' corresponding parts. I cannot see how to do this in the
> schema without anything equally as elaborate as we have in v0.5: I
> cannot see a way to avoid a situation where, if the 'predicate' at the
> level of child of 'shared' has a @mode attribute, it won't also have that
> same attribute available at child of 'testAssertion' level too.It still seems
> to me that what we have in 0.5, though complex, is as simple as it can be.
>
> Also, I think we need to start to determine rules for what we have as
> Section 3.2 in the 0.5 spec. Plus I need some confirmation as to whether
> Section 3.3 works for people ('Reserved Tag Names' - for properties and
> spec versions).
>
> Then I guess, since the review is finished, we may, if we agree, need to
> make the Test Assertion Guidelines into
> "Test Assertions, Part 1  Test Assertions Guidelines" (with normative
> language and to put on a path toward committee spec status).
> Plus we need to publish a list of all the comments and our dispostions.
>
> I could take all these as action items if folk agree.
>
> Best regards
>
> Steve
>
> ---
> Stephen D Green
>

Private Review (May 2009)
-------------------------


Issue 001: use of ID TA002a in 3.6.1

Description: Section 3.6.1 LIST (Dimensions of variability). It is unclear what is the use of ID TA002a. Instead of “Test Assertion Document” I prefer to use the term “Test Assertion List” or “Test Assertion Set”

Proposal 1 remove the "wrong" first example (with List Members: TA001, TA002, ..., TA008 ) and start directly from the right one. Add just a short note that it is not correct to shorten an enumeration by using ellipsis ('...').

Disposition:




Issue 002: Sect 2.1, (Figure) set of TAs

Description: Instead of “Test Assertion Document” prefer to use the term “Test Assertion List” or “Test Assertion Set”

Proposal 1 Replace Test Assertion Document with Test Assertion Set in the Fig.

Disposition:



Issue 003: Section 1.10 , Target Categories

Description: Section 1.10 Target Categories needs more clarification. For example, target categories consist of: target-isa, prefix notation, composition relationship. The example does not do the job.

Proposal 1

Disposition:



Issue 004: misleading statement in 2.2 Description: In 2.2: "The case of how to write a predicate for specification statements that convey optionality (for example, using keywords SHOULD, MAY, etc.) is examined later." This statement is misleading as it suggests that predicates are written differently from the MUST cases, which is not true.

Proposal 1 Replace with: "Predicates for specification statements that convey optionality (for example, using keywords SHOULD, MAY, etc.) are no written differently, as shown later."

Disposition:



Issue 005: Title of 2.2.3 Description: Title of 2.2.3 is misleading: "Optional Statements: Prescription Level" seems to suggest that Prescription Level is optional, while it is a mandatory part. This title is a clumsy summary of the solution described in the section for handling Optional Statements.

Proposal 1 Suggest new title: "Optionality in Normative Sources". 

Disposition:




Public Review (August 2009)
---------------------------


Issue 006: location of test assertion markup

Description: I'm looking for a formalized set of document constraints on an instance of tag assertions. Does one exist?

http://lists.oasis-open.org/archives/tag-comment/200908/msg00000.html

Proposal 1 add test assertion markup to Test Assertions Guidelines document and progress it to committee specification

Proposal 2 make a test assertion markup specification part 2 of a two part Test Assertions specification with part 1 being Test Assertions Guidelines document then progress both parts to committee specification

Disposition: