Re: Conformance Clause Template

Hi Karl, all --

I looked at the new-formatted SpecGL template [2] and the currently-linked 
template [1].  [2] is much better and clearer layout, and its content is in 
pretty good shape.  We still need to solve the IE problem with the CSS.  I 
have some relatively small comments and suggestions, which I list below, 
section by section.

[1] http://www.w3.org/QA/WG/2004/08/SpecGL-template-text.html
[2] http://www.w3.org/QA/2005/08/SpecGL-template-text.html


Global
----------
I like the inclusion of examples.  So I suggest that the Examples should be 
completed for all Step-sections.

"About this Template"
----------
1st pgph:  s/is the probably the/is probably/
2nd pgph:  delete 1st sentence, and merge 2nd & 3rd pgphs.

Legend:  s/Intrusctions/Instructions/

1st green-shade Ed note: delete it.
2nd green-shade Ed note:  this explanation ("virtual conf. clause for ... 
FooML") should be part of the "About..." section.  I suggest moving the 
sentence to just before the Legend.

Step 1
----------
Good, no comments.

Step 2
----------
Good, no comments.

Step 3
----------
As I read this, the RFC2119 boiler plate becomes part of the literal text 
of the template (automatically included in all CCs).  It should instead be 
one of the options.  In [1], there are two options:

<literal>The language and method of expression used for individual 
conformance requirements or testable statements in this specification 
is:</literal>
<option>RFC2119 keywords</option>
<option>Other (explain)</option>

[I'm just using markup to illustrate what I mean.]

Now, if RFC2119 option is used, then the the boiler plate should also be 
included.  (Note:  SpecGL itself does not use RFC2119 as the main form of 
expression of conformance requirements!  So it could be a good example of 
"imperative voice".)

Karl has already expanded "Other" to include "imperative style" and 
"descriptive style".  So perhaps the options list should be:

<option>RFC2119 keywords</option>
<option>imperative voice</option>
<option>descriptive/assertive prose</option>
<option>Other (explain)</option>

Step 4
----------
Good, no comments.

Step 5
----------
Suggest changing title from,
"Define how class of products impacts the conformance clause"
to
"Define classes of products in the conformance clause

Complete the suggested link, "@@Class of Product@@", to a CoP discussion or 
definition.

Step 7
----------
Good, no comments.

Step 8
-----------
s/Well-formed//

Step 9
----------
Each of the two optional literal bullets ends with "[instruct template user 
to ...]".  It would probably be best to either style those as an in-line 
"Instruction", or move them into the Instructions section.

Regards,
-Lofton.

Received on Sunday, 28 August 2005 21:43:02 UTC