about the "Guidelines specification" and its format

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

Following up on discussion last meeting:

 

Issue: both the TA model + TA markup are to be submitted as OASIS standard, and at some point to ISO.

So we need to make sure these material are packaged accordingly.

 

 

After reviewing the Test Assertions guidelines doc, it appears to me quite difficult to isolate examples from main body. It has been written on purpose as a "user guide". Even if we move Examples in appendix, most of the main text in section 4 revolves around these events, and that would be awkward and hard to read, defeating the user guide approach.

 

Two possible changes in editorial strategy, in addition to keeping the current approach and not change anything:

 

Solution 1:

- reposition the current Test Assertions guidelines doc as: "Test Assertions Model and Notation", going a little further toward a formal specification: e.g. the notation we used throughout the doc for examples (i.e. the "underlined" list of TA parts and their value), is made more formal (i.e. normative).

For example:

- the Predicate and Prerequisite MUST refer to the target using ' [ ' <target value> ' ] '

- the Predicate and Prerequisite MUST NOT contain any normative keyword (RFC2119...) and MUST be stated in form of an expression that is either true or false.

- references to other test assertions (from Predicate or Prerequisite) MUST be done using one of teh following format:

- <TA id>, which is a short notation for: <TA id> = "true"

- <TA id> '(' <target> ')', which is a short notation for: <TA id>  '(' <target> ')'  = "true"

- <TA id> '(' <target> ')'  = (true|false|notQualified)

- etc.

So each "advanced" subsection in section 4, could introduce its bit of notation, and illustrate it with boxed examples we curently have.

Then both the "Test Assertions Model and Notation" and the "TA markup" docs are packaged for the standard track.

 

Solution 2:

- Move the TA model that is at the beginning of the Guidelines (sections 3.1, 3.2), out of the Guidelines and into the TA markup, and make the latter a "TA model and markup" specification, with a clear separation between the model and the markup.

- Keep the informal intro material of the Guidelines, and keep this document as a pure "guidelines and best practices" doc, non normative, and NOT to be furthered as a specificaiton (a bit of content redundancy with the "TA model and markup" is inevitable, but OK).

- only the "TA model and markup" doc is furthered as a standard.

 

 

So we have 3 approaches:

 

- approach 0 = keep going the curent way.

- approach 1 =  solution 1 above.

- approach 2 =  solution 2 above.

 

Opinion?

 

Jacques